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ABSTRACT 






The APL emulator Is a microprogrammed 
Implementation of an APL processor. An APL 
processor provides direct execution of APL 
programs. This report defines the architecture 
of the APL processor and it gives the 
specifications of an integrated APL emulator. 
The APL emulator is said to be 'integrated' 
because it is co-resident with the IBM 370 
emulator and It can be used under standard 
operating systems such as OS or CP/CMS. 



This APL emulator is part of a system called 
APLM, APLM provides the user with all of the 
facilities of APL/360. APLM is fully 
operational. The APLM software is written in 
IBM 370 code and in APL. The APL emulator is 
written In IBM 370 model 145 microcode and will 
run only on a model 1U5. 
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1. INTRODUCTION 



APL/360 Is an Interactive time sharing system which 
provides interpretive execution of the APL language. 
Interpretive execution offers many advantages In producing a 
powerful, safe, and elegant programming language, but 
Interpretation Is typically much slower than direct 
execution. There are several aspects of the APL language 
which make it impossible to provide direct execution of APL 
statements using the machine language of existing computers. 
The only way of getting direct execution of APL is to 
construct a processor specifically for that purpose. 
Fortunately the reloadable control store, which Is a feature 
of some models of the IBM 370, allows us to construct this 
APL processor by the use of microprogramming. This manual 
defines the architecture of an APL processor and It 
describes an emulator for that processor. The APL emulator 
is co-resident with the IBM 370 emulator and the manual 
describes the Interaction between these emulators. If any 
processor Is to be used effectively then it must be embedded 
in suitable softv/are. The APL emulator runs under a 
software system which presents the user with all of the 
facilities of APL/360. We will use the name APLM to denote 
the system composed of the emulator and the associated 
software. 

The first part of this manual will explain some of the 
novel aspects of APLM and will review the overall working of 
the system. The later parts will give a precise definition 
of the architecture and of the interface between the APL 
emulator and the 370 emulator. 
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2. THE APL MACHINE 



The meaning of the expression 'IBM 7090 emulator' Is 
quite obvious; an emulator is a hardware assisted simulator 
and an IBM 7090 is a machine which Is specified by the IBM 
7090 theory of operations manual. The meaning of the 
expression 'APL emulator' does not become apparent until we 
have described an APL machine. Consider first of all the 
use of an IBM 7090. It will involve the following steps. 

(a) The programmer writes a program using symbolic 
Instructions such as 'CLA I' or 'STO J'. 

^^^ (b) The assembler allocates memory locations for the 

^ program and the variables I,J,... and it translates the 

§ program into an Internal representation whose octal 

form Is '050000 01001', '060100 01002', etc. 

(c) The loader loads the program into memory, possibly 
relocates the addresses, and supplies library routines 
as required. 

(d) Finally the loader issues an instruction which causes 
the first of the user's Instructions to gain control of 
the machine. The machine now executes the instructions 
specified by the user. 

In order to use an APL machine we follow some similar steps: 

(a') The programmer writes his programs in the APL language 
which is described in the 'APL/350, Users Manual', form 
number GH20-0906. A typical statement Is 'J< — K+L'. 

(b') A translator converts all statements and functions into 
internal form. The translation process is as follows. 
Convert operators and separators into a 2 byte internal 
form. Convert all names into a two byte internal form; 
the first name encountered by the translator is 
translated Into 006C (hexadecimal), the next is 0070, 
the next is 007*1, and so on for successive multiples of 
four. The Internal names 0000 through 0068 are 
reserved for system use. Having translated operators, 
names, and constants (see 'INTERNAL TEXT OF STATEMENTS' 
for translation of constants), reverse the order and 
add an end of statement marker. If '006C', '0070', and 
'007tt' are the internal names of J, K, and L and If 
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•1021', '7001' and 'AOOl' are the internal 
representations of ' + \ '< — ', and 'end of statement', 
then 'J< — K+L' has the internal representation '007ft 
1021 0070 7001 006C AOOl' . 

(c') APL is most effective in a time sharing environment, so 

the 'loader' is typically part of an APL supervisor. 

The supervisor allocates a workspace to the user and 

places the internal representation of statements and 

functions into the workspace. A workspace is simply a 

contiguous block of memory which holds the programs and 

data of a single user. The supervisor and the machine 

will provide input-output, formatting, trigonometric 

functions, etc., so the automatic 'library routine' 

loading phase of the load does not occur. The user may 

^ load APL library functions at a later stage. The APL 

^ supervisor may swap a workspace in and out of main 

^ memory, and the user may perform various editing 

functions but eventually the user will ask for 
execution and the APL supervisor will bring the 
workspace into main memory (main memory could be a 
virtual main memory). 

Cd') The supervisor Issues an instruction which causes the 
first of the user's statements to be executed. That 
first statement can, and usually will, invoke other 
user defined functions and so on. 

When a new machine is being designed It is usual to 
define the machine language and then the symbolic or 
assembler language. In the case of the APL machine, the 
symbolic language v^as defined first and now we define (later 
in this manual) a machine language; it would of course be 
possible to define other APL machines with other internal 
representations. The steps a', b', c', d' described above 
are used by APLM but of course similar steps are used by 
APL/360; the essential difference is that step d' is carried 
out by an Interpreter in the case of APL/360 and by a 
processor In the case of an APL machine. In our case the 
processor is microprogrammed (just as the IBM 370 model 11^5 
Is microprogrammed) but it could be all hardwired. 
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3. 



THE V/ORKSPACE ENVIRNOMENT 






The IBM 370 machine works on a partfcul 
at a time^ but it also makes use of a glob 
which is specified by the PSVJ, the contents 
storage locations and the 370 registers (fi 
floating). The APL machine works on a particu 
at a time, but it also makes extensive use o 
environment; the 'current environment' is 
workspace and the 370 registers. The act 
contains the users programs^ the values of a 
variables/ the current status, and the curr 
stack. If the current statement is in a func 
called from another function which was called 
function and so on, then the stack cont 
Information pertaining to these function 
information on the stack can be displayed 
commands )SI and )SIV. 
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The workspace is divided into four parts, namely 



Control 
Address 
Stack 
Free space 



words 
table 



There is a register denoted by 'WORKBASE' which specifies 
the address of the beginning of the workspace. The control 
words area contains certain fixed constants as well as 
current status information. The address table varies in 
size. The address table entry at location V/ORKBASE+n is a 
word which describes the properties of the variable whose 
internal name is n; thus if VJORKBASE contains 123U00 and 
variable d has internal name '006c' then the word at 
location 12346C is the address table entry for J. An 
address table entry has one of two forms: 

+ + 

I S P I D I V I 

+ _ — + 

+ + 

I S P I A I 

+ + 

S specifies whether the entry is a variable, a function, a 
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group name, or a shared variable. P specifies wfiether a 
variable has a value or not. If a variable has a value the 
value may be specified by D and V (scalar characters and 
logical or short integers are specified this way) or the 
value may be specified by the block of memory beginning at 
location A-4. 

Free space contains the current values of variables and 
functions as well as some unused space. The address 'A' in 
the previous paragraph is a free space address. If J is an 
array, its address table entry will point to a block of the 
form: 

+ + 

I D : J I V I 

+ + 

where D is a sixteen bit descriptor specifying that J is an 
array and indicating whether it is logical, integer, real or 
character. The half word shov;n as J contains the internal 
name of J. V contains the internal representation of: the 
ravel of J, the size of J, the rank of J, and the size of 
the ravel of J (see the APL/360 manual for the meaning of 
size and ravel). Later sections of this manual provide 
further details on the representation of functions and 
variables. 
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It. EXECUTION 

•the APL machine' stated that the supervisor issues an 
instruction which causes the first of the user's statements 
to be executed. What actually happens is that the APL 
system has translated APL statements and functions into an 
internal form and has stored them in the free space area of 
the workspace, and it has set one of the control words with 
the address of the first statement. Execution begins when 
the APL system puts the address of this workspace in 
WORKBASE and issues the macro 'APLSCAN'. The 'APLSCAN' 
macro then causes the APL emulator to select the appropriate 
control word, find the address of the first statement, and 
begin execution. 

The APL emulator directly executes statements such as 
the one illustrated in section 2 (a'), namely: 

007lt 1021 0070 006C AOOl 

The emulator obtains the first two bytes (700ii) and examines 
the last two bits; In this case these are 00 v;hich indicates 
an 'internal name'. The emulator forms VJORKBASE + 007ft and 
finds the appropriate S bits (see 'THE V^RKSPACE 
ENVIRONMENT'). Assuming that the S bits show that 0071j is a 
variable and not a function, the emulator notes this fact 
and selects the next Item. The low order bits of the next 
item (1021) indicate that it is an operator. The emulator 
now selects the 0070, finds its S bits, and, assuming that 
0070 Is a variable, the emulator starts to perform the 
addition of variable 007U and variable 0070. The first 
action Is to examine the P bits of 007if and check that the 
variable has a value (If not, to signal 'value error'), then 
check that it is numeric (If it Is character then signal 
'domain error'). Similar actions are performed for '0070'. 
Next the emulator checks to see If 0070 and 007^* are 
scalars, vectors, or arrays, and that their sizes conform. 
It then decides on the type (integer or real) of the result, 
obtains space for the result, does the additions, checks for 
range errors (exponent overflov^),, stores the result (v^hich 
may be a scalar, vector, or array) and finally proceeds to 
the next item In the statement. 

The execution of this expression has been described in 
some detail In order to demonstrate that the APL processor, 
does execute APL statements directly and Is fully cognizant 
of all the properties of the APL language. 
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5. INTEGRATED EMULATION 



The IBM 370 systems support a number of emulators. One 

of the outstanding features of these emulators Is that they 

are Integrated with the IBM 370 system; the IBM 1401 

emulator on the IBM 370 Model 145, for example, is not only 

co-resident with the 370 emulator, but it also runs under 

control of the standard IBM 370 operating system. There are 

many advantages to integrated emulation; it is possible for 

one to schedule the jobs with the standard operating system 

and It is possible to use IBM 370 devices for 'IBM lUOl' 

input/output. As a result, integrated emulation greatly 

extends the power, efficiency, and usefulness of the 

P_3 emulation process. The APL emulator is also an integrated 

(do) emulator and, with suitable software support, it will run 

g under any IBM operating system. 



presents some unusual problems which arise because tl 
machine architecture is so radically different from tl 
370 architecture. The IBM 370 and the IBM l^iOl (or tl 
370 and the IBM 7090) are quite different from each < 

U.. t. 4-1 J_ _1 .-^-!_ I •_ .. 



The implementation of an integrated APL emulator 
presents some unusual problems which arise because the APL 

:he IBM 
:he IBM 

— . — - - . _. . . „... other, 

but they do share certain basic properties: both machines 
use instructions, both machines use addresses, both machines 
recognize a limited number of operand types, both machines 
assume (with a very limited amount of checking) that the 
programmer will have decided which operator to use with 
which data (for example, integer add for integer data and 
floating add for floating data). The APL machine language 
has no instructions; rather, it has statements. The APL 
machine language has no addresses; it has names. The APL 
machine recognizes scalars, vectors, arrays of any size and 
shape. The APL machine applies an operator in many 
different ways according to the types of the operands. 
Despite the radical difference in architecture and despite 
many other problems, it has been possible to make an 
integrated APL emulator. Before considering the emulator, 
the basic mechanism of emulation on IBM 370 machines which 
have a reloadable control store should be examined. 

Figure 5.1 shows a block diagram of a simple 
uni-programmed second generation computer. The processing 
unit is all hardware; the memory contains a single program. 
In figure 5.2 we show a diagram of a multi-processor. The 
hardv/are has one PSW; the memory contains several programs. 
One program is active at one time and Its PSV; is in the 
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FIGURE 5.1: A SIMPLE UN I -PROCESSOR 
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hardware PSVJ register. The other programs are dormant. 
When the active program is terminated then its PSW and 
register contents are saved in its save area and the PSVJ and 
registers of another program are loaded. Figure 5.3 shows a 
b1ocl< diagram of an IBM 370 microprogrammed multi-processor. 
The processing is nov</ controlled by a processing unit and a 
microprogram residing in a control store. The processing 
unit of figure 5,3 is much simpler^ and performs far more 
primitive operations^ than the processor of figure 5.1. 
Typically^ the processor of figure 5.1 would contain 
floating point hardware, whereas the processor of figure 5.3 
has no floating point hardware. The floating point 
operations are done by a series of microinstructions under 
the control of a microprogram, MPSV/ denotes the 
microprogram status word. In a system like the one shov^n in 
^ figure 5.3/ the processor reflects the basic data formats 
(typically 8 bit bytes, 32 bit words, 2k bit addresses). On 
the other hand, the microprogram determines the instruction 
set of the machine. For further details see 'An 
Introduction to Microprogramming' (IBM form number 
GF20-0385). 

The use of microprogramming allows the processing unit 
to support a wide variety of operations. An IBM 370 with 
the APL and litOl emulators installed has a control store 
whose contents are shown in figure 5.tj. The 'I/O U^3IT 
CONTROL' microprogram performs the detailed control of 
certain I/O units, replacing the separate control units used 
in System 360. The 'I/O INSTRUCTIONS' microprogram decodes 
the 370 I/O instructions and commands, initiates I/O 
operations and posts the status of these operations. The 
'370 CPU EMULATOR' microcode emulates the IBM 370 non-I/0 
Instructions. The MPSVJ In the diagram indicates that the 
370 CPU microcode is in control, so the processor is 
currently executing the 370 instruction which is pointed to 
by the contents of the PSW. 

It Is obvious that the contents of the MPSVJ determine 
whether the machine Is executing I/O control, an I/O 
instruction, a 370 instruction, a l^tOl instruction, or an 
APL statement; the important question is how does the MPSV^ 
get set? Suppose the MPSV; points to part of the 370 CPU 
microcode. If a control unit function is needed then there 
Is a microcode trap, the MPSVJ is saved, the control function 
is done, the MPSW is restored, and the CPU microcode 
continues. There are a fev; other situations which cause a 
trap but In general the 370 microcode vn 1 1 retain control 
until the end of the current instruction (note that 
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'Instruction' always means a 370 instruction; we will never 
use 'instruction' to refer to a microinstruction). At that 
point/ If an interrupt Is pending tiien tiie microcode will 
switch PSW's/ but the 370 microcode still retains control. 
The 370 microcode reads the next instruction. If that 
Instruction is a 370 CPU instruction the MPSVJ gets set to 
point to the 370 CPU microcode. If that instruction is 
'APLEC the MPSW gets set to the beginning of the APL 
emulator microcode. The APL emulator will retain control 
until it reaches the end of a program, needs some supervisor 
function, or detects an interrupt pending (see later 
sections). The APL microcode is also subject to the normal 
microcode traps. If the APL emulator detects a request for 
APL I/O It calls the APL supervisor. The emulator Itself 
does not do any I/O. When the APL emulator decides to 
D=a relinquish control, it sets the PSW to point to a 370 
^ instruction and sets the MPSV/ to point to the beginning of 
.§ the 370 Instruction fetch microcode. 
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6. INTEGRATED EMULATION AND THE OPERATING SYSTEM 



A further feature of integrated emulation Is that all 
of the emulators will work under a single operating system. 
The APL emulator is independent of operating systems; it 
will work under DOS^ OS^ CP/CMS or any other system for 
which APLM software is provided, A single processor will 
typically have one APLM supervisor working under the overall 
supervision of OS. However/ the emulator will support any 
number of users under any number of APLM supervisors and in 
a CP system it will support any number of virtual machines. 
As we mentioned earl ier^ the APL emulator is invoked by the 
370 instruction 'APLEC XX' where XX Is a hexadecimal code 
^ which selects various entries Into the emulator. The APL 
emulator achieves Its operating system independence by the 
following means: (a) from the point of viev/ of OS (where OS 
stands for OS, DOS, CP/CMS, etc.) the APLEC Instruction 
behaves like any other 370 Instruction, (b) the emulator 
responds to interrupts in the standard 370 manner, (c) the 
emulator honors the wr I te-protect keys on main memory, (d) 
the emulator is re-entrant; when the emulator gives up 
control it saves the current status in the workspace 
belonging to the current user, (e) the emulator uses the 
dynamic address translation hardware in the standard manner, 
(f) the APL emulator does no I/O operations. To summarize 
the situation: the APLEC instruction Initiates a very 
complex action of APL emulation but from the point of viev; 
of the operating system, APLEC behaves like any other 
non-privileged 370 instruction. 



ioo 
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7. THE APLM SYSTEM 



The APLM system runs in an environment like the one 
shov/n in figures 5.3 and 5.k. The system could be written 
in IBM 370 code or APL code or a mixture of both. IVe 
decided that the APLM system should be v/ritten in IBM 370 
code. The prime reasons for this decision v;ere that we 
could make use of a large amount of existing code from the 
APL/350 system and also the development of the APLM system 
could go forward in parallel with the development of the 
emulator. The format of the APL/360 and APLM workspaces are 
quite different so any code which depends on the internal 
details of the workspace had to be completely re-wrltten. 
P_3 All of the code concerned with handling the terminals, doing 
[oo) I/O, swapping workspace, scheduling users and so on, is 
g virtually unchanged. In other words, the APLM system is the 
same as the APL/360 system except for minor changes in the 
supervisor and completely new code for the translator, the 
editor, the output format routine and the routines which do 
error recovery after a user or system error. The APL/360 
Interpreter is, of course, completely eliminated; calls to 
the interpreter are replaced by calls to the emulator. Some 
of the interpreter subroutines, such as the subroutine for 
domino (matrix inversion and least squares fit) are still 
required. These routines can be modifications of IBM 360 
code routines or they can be written in APL. The APL 
emulator has the ability to call system routines which are 
written in IBM 370 code or APL machine code. The APL 
emulator will directly execute such APL routines without 
copying them Into the workspace. 

The overall environment of a typical APLM system is 
like the one shown in figure 5.3. Referring to that figure, 
the first partition in memory will typically contain an OS 
operating system. One of the other partitions will contain 
the APLM system routines and slots for several workspaces. 
The machine will function like a normal IBM 370. OS will 
time-share the CPU between several partitions. VJhen the 
APLM partition is in control, then It wil 1 spend part of Its 
time In normal IBM 370 mode controlling terminals, swapping 
workspaces, etc. There will come a time when APLM Is In 
control and one particular workspace Is ready for execution. 
APLM will bring the workspace Into main memory, will set 
WORKBASE to point to the workspace and then will give the 
APLSCAN Instruction. APLSCAN Is a special IBM 370 
Instruction which alters the contents of MPSW (see figure 
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5.k) so that It now points to the APL emulator. The APL 
emulator does some checks and then, if all is well, it 
starts directly executing the APL code in the workspace. 

Anyone who writes some IBM 370 code tends to assume 
that this code is executed in contiguous time steps. v;e 
know that in practice the code can be interrupted after 
every instruction (and in a few cases in the middle of an 
instruction) and that quite frequently the supervisor will 
suspend one task and go off to do another task. The APLM 
system can assume (with some limitations discussed below) 
that the APLSCAN instruction is executed in a single 
contiguous time step. In practice, the APL emulator does 
test for interrupts at frequent Intervals and when they 
occur it saves the current status in the current workspace 
^ and hands control to the IBM 370 emulator and the OS 
supervisor. The OS supervisor will switch tasks in the 
normal v/ay and carry out its normal function. Eventually OS 
will resume execution of the APLM task. When the APL 
emulator gave up control, it saved the location of the 
APLSCAN instruction and set the PSV/ to point to an APLRESM 
instruction. VJhen OS resumes APLM execution it executes the 
APLRESM instruction which gives control back to the APL 
emulator which resumes work on the interrupted workspace. 
The one complicating aspect of this situation is that 
APL/360, and hence APLM, Is unlike a normal user program. 
APLM does sometimes take control from the supervisor and it 
can, therefore, get control during an APL emulator 
interrupt. At this stage, the APLM supervisor may choose to 
do some I/O, however, the only actions I t can take which 
affect the current workspaces are to set the quantum end 
flag or the attention flag or reset the resume PSVJ. The 
former actions will cause the APL emulator (when It gets 
control) to terminate the APLSCAN at the next convenient 
point. The reset PSW action Is abnormal and should only be 
used If there seems to be a system error. 

The microcode in the APL emulator does all 'store into 
memory' instructions using the protect key provided by the 
most recent APLEC Instruction. The APLM system ensures that 
this protect key allows a store Into the current workspace 
only. In the unlikely event of the system or the emulator 
making an error, then It could harm the current workspace 
but It cannot harm anything outside of that workspace. 

\'ie have so far discussed the typical situation of one 
APLM system under OS. The APL emulator Is operating system 
Independent. It could support several APLM systems under OS 
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or any other operating system. There are difficulties in 
doing thls^ but the difficulties lie In the system, not in 
the emulator. The APL emulator can run under CP or CP/CMS 
and It has successfully run over twenty virtual machines, 
each with their own APLM system, all apparently active at 
the same time. 
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8. DEFINITION OF THE APL PROCESSOR 



In this section v;e begin the task of providing a 
precise specification of the APL processor. We have a 
microprogrammed implementation of this processor, but v/e 
believe that the architecture described here would be well 
suited to a hardware or software implementation. 

In order to define the processor, it would be very 

convenient if we could refer to an up to date and complete 

formal definition of the language. Since this definition is 

not available we assume that certain APL concepts are 'well 

defined' and that the reader will knov^ the meaning of these 

^ concepts The current sources of Information on APL are the 

^ 'APL/360 User's Manual' (IBM form number GH20-0905), the APL 

-^ program product, and 'A Formal Definition of APL' 

(Philadelphia Scientific Center report number 320-3008 by 

R.H. Lathwell and J.E. Mezei). The processor also supports 

some new features of APL which are available in the 

experimental version of APL/360 produced by the Philadelphia 

Scientific Center. We assume that the following concepts 

are v;el 1 defined: 

1) Functions, statements, variables. 

2) The APL character set and the external (e.g. the 
typewritten) form of the language. 

3) The value of a variable. 
h) The workspace. 

5) The status of a workspace. 

6) The method of displaying the current status of the 
workspace, and the value (or 'no value') of any 
variable. 

7) For any given workspace which contains any given 
functions and variables, then the effects of 
'executing' any given statement are knov;n. 

The external effects of the execution are that an error 
message may or may not result and the workspace status and 
the values of the variables will usually change. An APL 
system will contain three major parts: 

The 'Translator' which translates statements and 
functions into Internal form and puts them In the 
workspace. 

The 'Processor' v;hlch operates on a workspace and which 
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usually changes its contents. 

The 'Display' which translates values and status into 
external form. 

It is one of the virtues of APL that the user can never gain 
direct access of the internal representation. The user must 
phrase his input in terms of the external language, and he 
must Interrogate the contents of the workspace by way of the 
display programs. An APL time sharing system will of course 
contain other major parts such as the scheduler, the 
swapping program, and so on, but these parts do not enter 
into this discussion. 

The following sections of the manual will define the 
^ architecture of an APL processor. They describe the 
Internal representations of the workspace, functions, 
statements, variables, etc. These definitions should enable 
the system programmer to write suitable Translator and 
Display programs. The definition of the actual APL 
processor is simply that: 

If APL statements and functions are transformed by the 
Translator into the form described here, 

and the APL processor is Invoked, 

and the Display program transforms the internal form of 
the resultant workspace into a suitable external form, 

then the displayed results will conform with the 'v/ell 
defined' results of APL. 

It might be thought that this is just a round about way of 
saying that the APL processor is simply a microprogrammed 
version of APL/360, but this is not so. APL/360 uses 
certain specific methods to compute the results of APL 
execution, but there are many other methods which can be 
used. The processor can use any method it chooses as long 
as it produces the correct results; see the sections on 'AP 
VECTORS' and 'SYNONYMS' for some non-obvious methods of 
producing results. There are many different Internal 
representations corresponding to any external 
representation. The processor can produce the result in any 
form as long as the displayed result is correct. To give 
one example, the vector 1 2 3 ... 100 will usually have an 
internal representation which takes 21; bytes of memory but 
It may use a representation which takes klG bytes or 816 
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bytes or indeed any number of bytes. 
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9. THE V/ORKSPACE 



A computing machine works in an environment and the 
execution of the machine causes the environment to change. 
In an IBM 370 operating in. non-privileged mode the 
environment is essentially the PSW, the registers (16 fixed 
point and h floating point) and a piece of the main memory. 
The non-privileged program can not change anything outside 
this environment but it can make a supervisor call in order 
to get information into and out of its environment. In the 
APL machine (that is the model 145 operating under the APL 
emulator), the environment is the workspace plus the 370 
registers. One of the registers specifies the location of 
^ the v;orkspace/ the other registers, and the contents of the 
workspace specify the current status of the job and of the 
workspace. The APL machine has no memory of its own; it 
simply operates on a workspace in the manner specified by 
the status and by the programs in that workspace. When the 
APL machine gives up control (for example in order to allow 
an interrupt to be serviced) it does not assume that when it 
regains control it will still be operating on the same 
workspace. 

The main areas of the workspace are shown in figure 
9.1. The system areas are used only by the APL system and 
are not discussed in this document (with minor exceptions- 
see 'DEBUGGING AIDS'). The other areas are summarized below 
and discussed in detail In the following sections. The 370 
registers are also discussed in a following section. 

Free space contains the user's variable values, APL 
functions and a block of unused space. The address table 
contains a complete description of variables which have no 
value and of some scalar variables. For other variables and 
for all functions, the address table contains a partial 
description and an address. The address points to a block 
in free space. The execution stack, or simply the stack, is 
a push down list used by the APL emulator. The control 
words contain status information, constants, save areas, and 
so on. 

Free space is used from both the bottom and top as 
shown. When there Is insufficient space left the emulator 
performs a garbage collection to reclaim any unused blocks. 
The stack and the address table both grow towards a definite 
boundary between them. Should one of them require 



06/20/72 LPASN - IBM CONFIDENTIAL Page 9.1 






SYSTEM AREA A 



CONTROL V/ORDS 



ADDRESS TABLE 
I 
I 
V 



(EXECUTION) STACK 



FREE SPACE (BOTTOM) 
I 
I 
V 

A 
I 
I 
FREE SPACE (TOP) 



I SYSTEM AREA B 

i 

+ 



<-— LOW CORE ADDRESS 



I 

I <~- HIGH CORE ADDRESS 



FIGURE 9,1 1 WORKSPACE FORMAT 
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additional space^ hoviever, the boundary may be dynamically 
moved. Note especially that the stack grows from high core 
addresses to low core addresses. V^hen we speak of the top 
Item on the stack v^e refer to the item most recently placed 
on the stack. Thus the top stack item is the stack item 
with the lowest core address. 



C=Q 
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10. THE CONTROL V/ORDS 



The control words contain constants, addresses, and so 
on, which help specify the current status of the v/orkspace. 
The only things not included which are necessary to 
completely describe the status of a workspace are contained 
In the registers (see '370 REGISTERS AMD 'GETV"). A map of 
the control words is given In figure 10.2; figure 10.1 gives 
a listing of the codes used in the map. Below Is an 
alphabetic list of the control v^fords and their definitions. 
The microcode Instructions can conveniently use only small 
displacements (<256). These can, hov/ever, be either 
positive or negative and thus GPRS Is used to point not to 
c=3 the beginning of the workspace, but higher up (at TMPSAV). 
^ In the codes CBYT refers to the control byte which Is the 
^ first byte of the word. In the definitions the phrase 
'Address table entry for ...' means that the item Is in free 
space (or in the system or Is an Immediate) and the control 
word follows the conventions described in 'THE ADDRESS 
TABLE", The control v;ord Is thus 1 I ke a reserved name for a 
variable vyhlch v/i 1 1 be used by the emulator or the system. 



BLANK Address table entry for a blank character 

scalar. 

BNDATS Address of the current boundary between the 

address table and the stack. This actually 
addresses byte zero of the first word below 
the stack words, 

CALL370F Address of the transfer vector for the 370 

functions, 

CHKl'^RD Vi'ord used on entry to the emulator to check 

that a v/orkspace Is properly pointed to. 
This word contains X' 3D89ftlBB' . 

E Address table entry for 2.718,., 
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D=3 



A 
D 
R 
S 



Absolute value - no base required 
Displacement - absolute needing a base 
Relocatable - an address in the workspace 
System address - treated like 'A' 
System address - treated like 'R' 
Save area - specialized treatment 



USED 


B 
E 
S 


CBYT 


A 
U 
V 

z 


WRDS 


- 


Rll 


. 



Used by both the emulator and the system 
Primarily used by the emulator 
Primarily used by the system 

Control byte uses address table conventions 

Control byte is unused 

Control byte contains part of the value 

Control byte is zero 

Actual number of storage words 

Displacement from GPRS 
(not used by the emulator) 



R0 3 



Displacement from GPR3 



FIGURE 10.1: CODES USED IN FIGURE 10.2 
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Kg 



R 


U 


C 


W 








E 


S 


B 


R 








L 


E 


Y 


D 











D 


T 


S 


Rll 


R03 


CONTROL 


A 


E 


V 


1 


2F8 


-A8 


TIDYS 


A 


B 


V 


3 


2FC 


'Ak 


FUZZCTL 


A 


E 


V 




308 


-98 


SEED 


- 


- 


- 




30C 


-9k 


UNUSED 


S 


E 


u 




310 


-90 


CALL370F 


S 


B 


V 




51k 


-8C 


QEND 


s 


E 


u 




318 


-88 


SCANRTN 


s 


E 


u 




31C 


-84 


SERVRTN 


A 


E 


V 




320 


-80 


INTRTN 


X 


E 


V 


9 


321+ 


-7C 


SAVELS 


X 


E 


V 


9 


31*8 


-58 


SAVELSB 


X 


E 


V 


9 


36C 


-34 


SAVTDY 


D 


E 


z 




390 


-10 


FREES 


D 


E 


z 




59k 


-OC 


FREET 


A 


E 


V 




398 


-08 


CHKWRD 


D 


S 


z 




39C 


-04 


FRSTRELO 


X 


E 


V 




3A0 


00 


TMPSAV 


- 


- 


- 




3A8 


+ 08 


UNUSED 


A 


B 


A 




3BC 


+ 1C 


XARGO 


A 


E 


A 




5C0 


+ 20 


BLANK 


A 


E 


A 




3Ck 


+ 24 


ZEROVAR 


A 


E 


A 




3C8 


+ 28 


ONE 


$ 


E 


A 




3CC 


+ 2C 


REALl 


$ 


E 


A 




3D0 


+ 30 


PI 


$ 


E 


A 




3Dk 


+ 34 


E 


$ 


E 


A 




3D8 


+ 38 


MIN 


$ 


E 


A 




3DC 


+ 3C 


MAX 


- 


- 


- 




3E0 


+ 40 


UNUSED 


$ 


E 


A 




3EU 


+ 44 


NULNUMVC 


$ 


E 


A 




3E8 


+ 48 


NULCHRVC 


A 


B 


A 




3EC 


+ 4C 


INDEX 


A 


B 


A 




3F0 


+ 50 


FILL 


R 


E 


A 




3Fk 


+ 54 


TMPNAM 


D 


B 


A 




3FC 


+ 5C 


FUNCTION 


R 


B 


A 




400 


+ 60 


NEXT INST 


R 


E 


A 




kOk 


+ 64 


TSADR 


R 


E 


A 




408 


+ 58 


BNDATS 



FIGURE 10.2: CONTROL VVORD MAP 
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FILL 



FREES 






FREET 
FRSTRELO 
FUNCTION 
FUZZCTL 



Fill character to be used by APL 
routines. Set by the emulator 
right argument is numeric or 
character. 



coded system 
to if the 
to blank If 



Displacement of the start of free space plus 
k (le, GPR3 plus FREES is the address of the 
word after the dummy block at the bottom of 
free space). 

Displacement of the first word after the top 
of free space. 

The displacement of the first control word to 
require relocation if the workspace is moved. 

The Internal name of the current APL 
function. 

Three v/ords for fuzz control. The last two 
have zero at the fuzz bit; otherv/ise they are 
complementary. The first of these has zeros 
to the left of the fuzz bit and ones to the 
right. The first of the three words has 
bytes RS LM LO LF where ... 

LF number of half bytes to the right 
of the half byte containing the 
fuzz bit 

LO least exponent such that the 
(normal ized) number may be unequal 
to zero 

Lm Mask for testing the first half 
byte in cases where the exponent is 
LO (this is the half byte with the 
fuzz bit from the last of the three 
words) 



INTRTN 



RS reserved for the 
this happens to 
fuzz bits) 



system (currently 
be the number of 



This contains an APLRESM macro. The emulator 
points the 570 instruction location counter 
at this when taking an Interrupt. 
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c=o 



INDEX 
MAX 
MIN 
NEXTINST 



NULCHRVC 

NULNUMVC 

ONE 
PI 

QEND 



REALl 
SAVELS 



SAVELSB 

SAVTDY 

SCANRTN 

SEED 



If X indexes an operator this contains the 
cellinfi of X less the workspace origin. 

Address table entry for the largest possible 
real number (X'7FF...'). 

Address table entry for the smallest possible 
real number (X'FF...'). 

Address table entry for the next APL 
instruction half word. Byte of this 
control word is unused but is not preserved 
by the emulator. Thus it must be given 
special attention by the system relocate 
routine. 

Address table entry for a null character 
vector. 

Address table entry for a null numeric 
vector. 

Address table entry for 1 (logical). 

Address table entry for 3.141... 

Quantum end control word. Byte contains 
the switches (see '370 REGISTERS AND 
•GETV'). Bytes 1-3 contain the address of 
the system quantum end routine. 

Address table entry for 1 (real). 

Save area for the non-370 registers used by 
the emulator at interrupt (or other 
checkpoint) times. The area format is given 
in the 'DEBUGGING AIDS' section. 

Backup area for SAVELS. 

Save area for the TIDY microcode routine. 

Location of the 370 instruction following the 
last APLSCAN. 

Random number generator's seed value. 
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SERVRTN 



TMPNAM 



Location of the 370 Instruction following the 
last APLxxxx where xxxx specifies some 
service function (TIDY^ FIND, etc). 

Address table entries reserved for temporary 
use by the emulator during stack extension, 
function call, etc. These two v;ords are 
sometimes referred to individually as TMPNAMO 
and TMPNAMl. 






TMPSAV 
TIDYS 



TSADR 



Temporary save area for the emulator. 

Garbage collection count. This word Is 
Incremented by one every time TIDY Is 
Invoked. Overflow Is not tested for so 
negative values will follow the largest 
positive value and will eventually turn into 
positive values again. 

Address table entry for byte of the next 
available word on the stack. 



UNUSED 
XARGO 

ZEROVAR 



Currently unused. 

Extra argument (ie, 'global') for APL coded 
system functions. 

Address table entry for (logical). 
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11. THE ADDRESS TABLE 



The address table consists of a series of single word 
entries for the various internal names. Any of these 
Internal names may correspond to a user's external name^ 
such as 'A' or 'FUN'3', or it may be a name that the APL 
system Is using for another purpose, such as pointing to the 
'print name' for some internal name. The APL emulator may 
be mal<ing temporary use of a name to identify an 
Intermediate result such as A+B or a name may not be in use 
at all. The full details of the address table entries are 
given in figures 11.1 to 11. U. 

^ The first byte of the address table entry consists of 

g four syntax bits and four primary descriptor bits. The 
-^ syntax bits might, for example, identify the named item as a 
function of tv^o arguments or as a variable (see 'STATEMENT 
SCAN AND SYNTAX ANALYSIS' for a description of the syntax 
blts^ and their use). The primary descriptor bits 
distinguish between permanent and temporary items, tell 
whether^ or not a variable has a value, and If it does. 
Identifies it as an addressed value or an immediate value. 
Entries with addresses point to byte of the ON word (see 
*FREE SPACE'). 

A variable with an immediate value is called an 
address table immediate' and Is a scalar character, 
logical, or small integer. Character Immediates have their 
value In the last byte; the next to last byte is unused. 
Logical Immediates have their value In the last bit; the 
remaining bits In the last two bytes are zero. Integer 
Immediates have a 16-bit value In the last tv;o bytes and a 
seventeenth sign bit which Is replicated throughout the 
first two bytes when the value Is extended to a full word. 

The second word of FPR2 is Oi^OONNNN where NHNN is the 
next available unused name. Whenever a name, say RRRR, is 
released to become 'unused', the FPR2 word is stored In the 
address table entry for RRRR and then the FPR2 v/ord is 
changed to OitOORRRR. This yields a chain of unused names as 
shown In figure 11.5. V^hen a name is next requested RRRR 
will be given and the address table entry for RRRR read out. 
Since this entry is a link in the unused name chain it will 
replace the FPR2 word and we thus have restored FPR2 to 
OiiOONNNN. if three more names are requested v;e will give 
MNNN and QQQQ In the same manner. Then we will give TTTT, 
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C=Q 



SSSS POPP AAAA AAAA AAAA AAAA AAAA AAOO 
SSSS PIPP MUUU DDDD WW WW WW WW 



SSSS 

pppp 

A. .A 
V.,V 
DDDD 
MUUU 



Syntax (see figure 11.2) 

Primary descriptor (see figures 11.3 and 11. U) 

Absolute (virtual) address of the named block 

Value 

Type descriptor (O = logical, l = integer, ij=character ) 
Sign and unused 



FIGURE 11.1: ADDRESS TABLE ENTRY FORMS 



SSSS=0 
SSSS=2 
SSSS=3 
SSSS=9 
SSSS=B 
SSSS=C 
SSSS=F 



Unused name 

Variable, non-shared 

Function^ dyadic 

Function/ ni 1 adic 

Function, monadic 

Variable, shared 
Group 



FIGURE 11.2: POSSIBLE ADDRESS TABLE SYNTAX BITS 



PPPP=0 
PPPP=U 
PPPP=7 
PPPP=9 
PPPP = B 
PPPP=F 



Unused name not on unused name chain 
Unused name on unused name chain 
Permanent with no value 
Temporary with addressed value 
Permanent with addressed value 
Permanent with Immediate value 



FIGURE 11.3: POSSIBLE ADDRESS TABLE PRIMARY DESCRIPTOR BITS 



BIT 


h 


BIT 


5 


BIT 


6 


BIT 


7 



0=Has no value 
0=Addressed value 
0=Temporary 
0=Not in use 



l=Has value 
l=lmmediate value 
l=Permanent 
l=ln use 



FIGURE 11. If: ADDRESS TABLE P-BIT ASSIGNMENTS 
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but when the TTTT address table entry is read out It will be 
found to not be a link in the unused name chain. In this 
case four will be added to the FPR2 word to produce a next 
available unused name of UUUU. At the same time a check 
will be made to insure that UUUU is a valid name and not the 
lowest word in the stack area. This test consists of seeing 
that byte of the UUUU entry is zero. Alternatively one 
could make a comparison with the contents of BNDATS. 



C=3 
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FPR2 



c=o 



MNNN 

QQQQ 
RRRR 



TTTT 
UUUU 



I I 
lOIiOORRRRl 



I IM USE I 

I : I 

UN USE I 
+ ---IOUOOQQQQK-- + 
I UN USE I I 

+ — >|Ot*OOTTTT|---C-- + 
IIN USE I II 

>|0iiOONNNN| + I 

jIN USE I I 

II N USE I I 

lOOUUUUUUK + 

I : I 

loouuuuuui 



FIGURE 11.5: UNUSED NAME CHAIN EXAMPLE 
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12. THE STACK 



12.1 The Use of the Stack 

The stack consists of four registers denoted by Rl, R2, 

the 370 registers GPRl^ GPR9, 

of memory locations M<TS + ii>, 

is the beginning of the stack. 

its minimum allov/able value is 



R3/ Rk (actually these are 
GPR7, GPRE) and a sequence 

M<TS+8>, M<BS>. M<BS> 

in TSADR and 



TS 
in 



is contained 
BNDATS. 






Me v;ould like to avoid repeated memory references so we 
keep the top stack items in registers and allov/ these 
registers to be marked 'empty'. The action of pushing an 
item onto the stack is as follows: 

If Rk is 'empty' then go to OK 

If M<TS> is 'end stack' then extend the stack area 
M<TS> <-- Rk and TS <— TS-£| 
OK: Rk <— R3, R3 <— R2, R2 < — Rl and Rl <— item 



The end of stack marker is the same as an 'empty' 
marker^ a zero first byte. An empty item can occur in the 
registers, but the emulator never puts one on to the memory 
part of the stack. Hence an empty marker can be used to 
denote the end of the stack. At the beginning of execution 
TS=BS-U and the stack setup Is as follows ('U' denotes an 
unused half-byte): 



Rl 
R2 
R3 
Rk 
M<BS> 

M<BS-i*> 

A< BNDATS + It > 
M<BNDATS> 



undefined 
07UUUUUU - 'null ' 
undefined 
OOUUUUUU = 'empty' 
08UUUUU2 - 'begin stack' 

anything but 'empty' 

• 

anything but 'empty' 
00000000 (hence 'empty') 



\'}e nov/ begin execution with the sequence: 

BEGIN: R3 <— Rk 

Rk <— 'empty' 

Rl <— read next (first) APL token 
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Analysis and execution nov/ proceed with the setup: 

Rl APL token 

R2 'null' 

R3 'empty' 

RU 'empty' 

At the beginning of, for example, a dyadic operation the 
stack registers will be: 

Rl left argument 

R2 operator 

R3 right argument 

Rk next item on the stack 

M The microcode that executes the operator v/ill leave the 
^ result in R2. It can then branch back to the above BEGIN. 
-S See 'STATEMENT SCAN AND SYNTAX ANALYSIS' for further 
deta lis. 



12„2 Items on the Stack 

This section describes operators, names and values on 
the stack. The stack can also contain blocks of information 
and special stop words (see 'FUNCTION INVOCATION'). 

Each Item on the stack Is a full word. Bits 0-3 are 
the syntax bits and Identify the item as an operator, 
variable, separator, etc. A complete list of syntax codes 
Is given In the 'STATEMENT SCAN AND SYNTAX ANALYSIS' 
sect Ion , 

Operators go on the stack with hexadecimal form 
*1ABCUUUU' where 'lABC denotes their opcode and 'UUUU' 
denotes unused. The opcodes may go through minor 
modification during processing, such as setting of the 'Is 
Indexed' bit. The various opcode bits are further specified 
In the 'OPERATORS AND SEPARATORS' section. 

A name on the stack has the bit form 

SSSS UUUl UUUU UUUU NNNN NNNN NNNN NNOO 

where the U bits are unused, the N bits give the name and 
the S bits give the syntax code. The only syntax codes that 
should occur with names on the stack are 2=variable, 
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3=dyadlc function, 9=nnadic function and B=monadlc 
function. \i}e do not stack the name's P-bits because they 
may be altered while the name Is on the stack. 

Immediate values may be on the stack with the bit form 
0010 1110 MUUU DDDD WW WW WW WW 

With the exception that the P-blts are 1110 rather than 

1111, this is formatted exactly like an address table 

immediate. However, there Is a fundamental difference. 

Address table inmediates are always permanent variables; 

stack Immediates are alv/ays temporary variables. In a 

statement like 'B<--(A<--1.5)+A' A may go on the stack when 

It is an address table immediate but it will change to a 

M non- immediate before the stack entry is used. Because of 

^ this respecif Icat ion problem address table immediates must 

-S be put on the stack In the name form (as opposed to the 

Immediate form). Temporary results like 2+3 cannot be 

respecifled, so they are made into stack Immediates if 

poss ible. 
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13. FREE SPACE 



Free space is divided into blocks of words. The first 
and last blocks of free space each consist of exactly one 
v;ord containing the integer five. The reason for these two 
dummy blocks will be discussed later. First let us look at 
the basic items which may occur in free space (figure 13.1). 

There Is only one unallocated block. Whenever space 

must be found for an object, the required amount will be 

removed from the top or bottom (alternately) of this block. 

The first v/ord of the block is pointed to by FREEU (see '370 

REGISTERS AND 'GETV"). The rightmost bit of FREEU is 1/0 

c=3 for the next space to be removed from the top/bottom. The 

^ bit before this bit may have any value, but it will not be 

.g^ preserved by the emulator. 

The second word of an active block is called the 'DN 
word'. N is the internal name of the block. Each active 
block is associated with a word at location GPR3+M. This 
word has the format SPAAAAAA (see 'THE ADDRESS TABLE' 
although this word is not necessarily located in the address 
table) where AAAAAA is the address of byte of the DN word. 
D is a half v/ord which describes the block. Further details 
about active blocks will be found In the sections specif icly 
about them: 'VARIABLES IN FREE SPACE', 'AP VECTORS' and 
'SYNONYMS'. 

A garbage block is formed whenever an active block is 
freed. Whenever this happens the preceding and following 
blocks are also checked and, if either/both of them is/are 
Inactive (garbage or the unallocated block) then It/they are 
merged with the newly freed block. Thus free space should 
never contain tvio adjacent inactive blocks (actually the APL 
system may generate this situation during cases, like 
editing, where it directly plays with free space). The 
first and last dummy blocks in free space aid in this 
merging procedure; by having an odd space management control 
word (the first and last words of any block contain Its 
space management control v;ord) they look like active blocks 
and thus freeing the first or last real block does not have 
to be a special case for the merging routine to look out 
for.' We thus see v/hy the dummy words are used and why they 
contain an odd number. Nov; why is it five? When the 
garbage collector scans free space these blocks look like 
active blocks, but with zero bytes for the interior the 
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UNALLOCATED BLOCK 



I X + 2 I 



X-h BYTES OF SPACE 



I X + 2 I 



C=3 



GARBAGE BLOCK 
+ + 

I I 

I X I 

I I 

+ + 



X-h BYTES OF SPACE 



I I 

I X I 

I I 

. + + 



ACTIVE BLOCK 



I X + 1 I D 



I 

N I X-8 BYTES OF SPACE 



I X + 1 I 

I I 

■ + + 



FIGURE 13.1: BASIC FREE SPACE BLOCKS 



+ ■ 

I 

I 

I 

+ - 



• + • 
I 
I 

I 

+ - 



INTERIOR 



■ + 
I 



SPACE MANAGEMENT CONTROL WORD EQUAL TO B+T-4 
WHERE B IS THE TOTAL NUMBER OF BYTES IN THE 
BLOCK AND T IS 0/1/2 ACCORDING TO THE TYPE 
BEING GARBAGE/ACTIVE/UNALLOCATED (IF ACTIVE 
THE INTERIOR MUST BEGIN WITH A DN VJORD) 



FIGURE 13.2: GENERAL FREE SPACE BLOCK 
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block. Since this cannot occur for a true free space block 
the routine detects the end of the scan, 

\i\th the exception of the tv;o dummy blocks all of the 
above may be summarized by figure 13.2. 



(s3 
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Ik. VARIABLES IN FREE SPACE 



The very general form of variables In free space v;as 
described In the 'FREE SPACE' section. The more specific 
forms are shov/n in figure m.l. All items are full v/ords 
and are full v;ord aligned. The various Vi represent the 
value v/ords. V^e also have the element count In E, the rank 
in T, and the shape in Rl R2 .. RT. U...U denotes an 
undefined number of undefined words. This is usually null 
but an expression like 'A<-~,A' may produce a non-null case 
(see 'SYNONYMS'). The possibility of non-null U...U means 
that the location of E must be computed as follows: Let d 
be the address of the DN v^ord. Then the address of E I s d-8 

^ plus the contents of d-k. T, RT, ... can be accessed by 

^ stepping backwards from E. 

integers are stored in full v/ords and reals are stored 
in full v/ord pairs (but not necessarily double v/ords) using 
the standard 370 representation. Characters are stored 
sequentially from left to right In bytes and padded on the 
right with undefined bytes if necessary to complete a v/ord. 
The^ bit patterns used for character representation are 
defined by the APL system and are of no concern to the 
emulator. The emulator only needs to know the 
representation for a blank (for the expansion and take 
operators) and for this ft uses the control word BLANK. 
Logical vectors are stored with eight values per byte and 
these bytes are stored sequentially as in the character 
case. Vi/Ithln a byte the values are stored from right to 
left. Hence a logical vector v/ould begin with the elements 
E7 E6 E5 Ek E3 E2 El EO In the first byte and E15 E1I| E15 
E12 Ell ElO E9 E8 In the second byte. The byte containing 
the last element will be padded with undefined bits on the 
left if necessary. 

The descriptor is delineated in figures 14.2 to Ik.k. 

It is a half word consisting of bytes DO and Dl. DO is the 

'escape' descriptor and is usually zero; the only exceptions 

are hexadecimal values of '01' for synonym links (see 

'SYNONYMS') and '01^' for AP vectors (see 'AP VECTORS'). Dl 

uses bit to flag these escape cases. Dl has bit h always 

off. However, v/hen the nlcrocode Is using a variable, a 

copy of the descriptor exists in the GPR's. In this copy, 

bit h of Dl may be used to flag Initialization of the 

variable by some micro-routine, etc. The descriptor bits of 

most interest are bits 123 and 557 of Dl; these are well 
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NON-REAL SCALAR 
REAL SCALAR 
VECTOR 
ARRAY 



C DN VO U...U C 

C DN VO VI U...U C 

C DN VO VI .. VN U...U E C 

C DN VO VI ., VN U...U Rl R2 



RT T E C 



FIGURE lli.l: FORMAT OF VARIABLES IN FREE SPACE 



(IT 


MEANING IF ON 





ESCAPE CASE 


1 


NOT SINGLE VALUED 


2 


ARRAY 


5 


ARRAY OR VECTOR 


k 


(ALWAYS OFF) 


5 


CHARACTER 


6 


REAL 


7 


REAL OR INTEGER 



FIGURE III. 2; SECOND DESCRIPTOR BYTE DEFINITION 



BITS 123 CASE 



BITS 567 CASE 



000 


SCALAR 




000 


LOGICAL 


001 


VECTOR, E 


is 1 


001 


INTEGER 


oil 


ARRAY, E 


is 1 


Oil 


REAL 


101 


VECTOR, E 


not 1 


100 


CHARACTER 



111 ARRAY, E not 1 



FIGURE lh,3t SECOND DESCRIPTOR BYTE CASES 
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1^ 



BIT MEANING 

(CURRENTLY UNUSED) 

1 (CURRENTLY UNUSED) 

2 (CURRENTLY UNUSED) 

3 (CURRENTLY UNUSED) 

k 1 IF AND ONLY IF AP VECTOR 

5 (MUST ALWAYS BE SO) 

6 (MUST ALWAYS BE SO) 

7 1 IF AND ONLY IF SYNONYM LINK 



FIGURE 14. l>: FIRST DESCRIPTOR BYTE DEFINITION 



SCALAR: 100000 

OOOOOOOD OOOlnnnn 000186AO OOOOOOOD 

SCALAR: .5 

00000011 0003nnnn itOSOOOOO 00000000 00000011 

VECTOR: .5 

00000015 0013nnnn 1^0800000 00000000 00000001 00000015 

VECTOR: NULL (CHARACTER) 

OOOOOOOD 005f+nnnn 00000000 OOOOOOOD 

VECTOR: 'ABCDEF' 

00000015 OOStjnnnn ClC2C3Clt C5C60000 00000006 00000015 

ARRAY: VALUES=1 10 1111 SHAPE=3 3 
OOOOOOID Q070nnnn E5010000 00000003 00000003 00000002 
00000009 OOOOOOID 



FIGURE lit. 5: EXAMPLES OF VARIABLES IN FREE SPACE 
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described by figures li*.2 and 1U.3. Particularly useful is 
bit 1^ the 'pseudo scalar' bit. If this bit is on the 
variable is null or has more that one element. Thus if the 
bit is off, according to the rules of APL, it can frequently 
be used as a scalar, whether or not it is one. 

Some examples are given in figure lit. 5. Characters are 
shov/n in EBCDIC but the APL system may use a different code. 



c=o 
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15. AP VECTORS 



An AP 
ar 1 thrnet i c 



vector is a vector of integers 
)rogression. Some examples are: 



which form an 



1 
10 
17 



2 

13 

3 



3 

16 

-11 



19 
-25 



22 



25 



c=o 



Any AP vector can be represented 
element, step between elements, 
internal form for an AP vector 
numbers are hexadecimal). 



n a compressed form: first 

number of elements. The 

is as shov/n belov/ (all 



0000 



I 



I 



I 



+ +. + + + + + 

I 
I 

I 

+ -I- + + + + 



001510401; 



NAME I FIRST | DELTA | NUM ELM 1 0000:0015 1 
I I I I : 



Thus the above examples would become: 



00000015 
00000015 
00000015 



O^Dlxxxx 
OiiDlyyyy 
OUDlzzzz 



00000001 

OOOOOOQA 
00000011 



00000001 
00000003 
FFFFFFF2 



00000003 
00000006 
OOOOOOOU 



00000015 
00000015 
00000015 



The APL emulator does not examine all vectors to see if 
they can be represented as AP vectors. But the iota 
operator always generates an AP vector if the element count 
is greater than one and the emulator v;ill preserve AP 
vectors across many operations such as addition of a scalar 
(do one addition instead of n of them) and multiplication by 
a scalar (do two multiplications instead of n of them). 



AP vecto 
one mi 1 1 ion' 
able to sum 
importance, 
frequently us 
iota vector, 
these subscri 
1 i sts, al low 
recognize ma 
There are oth 
let TEXT be a 
Then the emul 



rs permi t 

to exist in 
reduce it 
hov/ever, 

e subscript 
AP vectors 

pts. They 
the sub 

ny special 

er instance 
string of 

ator will e 



many stunts such as allov^ring 'iota 
a small v^orkspace and such as being 
in very little time. Their real 
is in subscripting. Programs 

s of the form 'A+BxC where C is an 
allov^ very efficient processing of 

also, in conjunction vnth subscript 

scripting microcode routines to 
cases for efficient evaluation. 

s of real use as well. For example, 
N characters and let IN be iota N. 

valuate 
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(TEXT= 



_t I 



)/IM 



in less time and core space than v;ould be possible without 
the use of AP vectors. 



0=3 
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16. SYMOMYMS 



If B is a vector or an array, then A<--B vjil] usually 
cause A and B to become synonyms. In this case a single 
copy of the value block will be stored and both A and B v;lll 
refer to this block. The use of synonyms will reduce the 
space and running time of most APL programs. Assuming that 
B is not already a synonym, figure 16.1 shov/s what happens 
for this assignment. T is a temporary name and U is 
undefined. The quantities shown in the blocks (A, B, C, D, 
T, U and -1) are all half word items. The descriptors of A 
and B will have the synonym descriptor bits on (see 
•VARIABLES IN FREE SPACE'). 

Several items can be synonymous; suppose A, B and C are 
synonyms. Then the last tv;o items in the blocks which their 
address table entries point to are: 

A: -1 B 
B: AC 
C; B -1 

In other words these items show the neighboring items on the 
synonym chain with -1 (actually any half word with the low 
bit on) indicating the end of the chain. If the statement 
D< — B occurs then the synonym chain becomes A, B, D, C so 
that the links Items become: 



A: 


-1 


B 


B: 


A 


D 


D: 


B 


C 


C: 


D 


-1 



A synonym is set up if B is a medium or large nonscalar 
(currently this means that the space management control word 
is less than 64; see 'VARIABLES IH FREE SPACE') and one of 
the following Is done: 

B DF E where DF is a dyadic function 

MF B where MF is a monadic function 

A<--B and the result will not fit in the old A 

/B where B is an array 

The last case implies that the various synonym links may 
have different descriptors and that these descriptors, not 
the one In the value block, describe their associated 
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BEFORE THE ASSIGNMENT 

+ + 

I ADDRESS TABLE 



ENTRY FOR A 



■> ? 



ENTRY FOR B 



•>| D B I VALUES AND SIZE | 



C=3 



+ -. + 



AFTER THE ASSIGNMENT 

+ -■ + 

ADDRESS TABLE 



ENTRY FOR A 



+ -- + + + 

>| D A I U T I -1 B I 



ENTRY FOR B 



+ + + + 

■>l D B I U T I A -1 I 
+ + + + 



ENTRY FOR T 



+ + + 

•>| D T I VALUES AND SIZE | 
+ + + 



+ ■ + 



FIGURE 16,1: ADDRESS TABLE AND FREE SPACE ITEMS 
BEFORE AND AFTER A<— B (THE SPACE 
MANAGEMENT CONTROL l/ORDS flAVE BEEN 
OMITTED FOR SIMPLICITY) 
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variables. The last two cases imply that if B is an array 
then A<— ,B will usually set up a synonym block and that 
B< — ,B will simply change the descriptor of B. 

If A and B are synonymous then A<— X will cause the old 
value of A to be freed and the assignment to be done. If B 
was synonymous only with A the the synonym chain reduces to 
-1 -1 and In this case the synonym block is freed and B is 
made to point directly to the value block. 



0=0 
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17. OPERATORS AND SEPARATORS 

Operators and separators are represented in 16 bits of 
the form: 

SSSS DDDD DDDD DDOl 

The last two bits are zero-one and they specify that this is 
an operator or separator. The first four bits specify the 
syntax (see 'STATEMENT SCAN AND SYNTAX ANALYSIS'). The 
D-bits distinguish between the various operators. There are 
some special operators (see 17.4) which have non-standard 
form. 



17.1 Operators 

Operator codes are shown in figures 17.1 and 17.2. 
They have the form: 

0001 CRZM DEFG HIOl 

The bit patterns for individual operators are arranged so 
that the emulator can quickly detect various groups of 
operations. The bits have the following significance: 

C=l for equal and unequal 

R=l for left and right slash (and their '-' 

overstrikes) and for period 
Z=l for operators overstruck with '-' 
M=l for mixed operators 
E=l for indexable operators 

In the case of scalar operators (M=0) FG is GO for 
comparisons and 01 for logical operations. Also, in the 
scalar operator case, character arguments produce a 'domain 
error' unless C = l. If the emulator detects tv/o contiguous 
operators and if either has R=l then it checks for 
reduction, scan or inner or outer product. When the 
emulator Is actually performing an operation it usually 
holds the operator in the left half of GPR9. However, it 
may change certain bits to indicate special conditions. For 
example. In scalar operations E is usually set to 1 if real 
arithmetic is needed. Also, Z is set to 1 if an operator is 
explicitly indexed. The operators with M=l and F=l cause an 
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DO) 



1 5 9 D 1 5 9 D 

+ _„_ + + + ---+ + + + + + 

100 I I ! < I < I 110 I p I f I I I ± I 
+ --- + + + + + + + + + 

101 I V 1 A I V I ty I 111 I o I I I I 
+ „-_ + + + + + + + + ^ 

102 !+ I X I r I I I 112 I I I \ i \ I 
+ --- + + + + + + + + + 

103 I * I ? I O I I 113 I I I I B I 
+ --- + + + + + + + + + 

108 I I I > I > I 115 I i I 4) I i I 
4..^_ + ___ + + . + + + + ^ ^ 

109 I 1^1 ! ~ I 118 i fc? I + I € I T I 
+ »_„ + ___ + ___ + _._+ + + ^ ^ ^ 

« 10^ I - 1 I I L I I 11>1 I B I I T I * I 

jj.. — + + + + + + — ^ + + 

los I ® I I f I I iiB I B I I I B I 

+ --- + — + — + — + + — + — + — + — + 

180 I 1=1 I I IID \ I I . I t I 

+ „„_ + + + + + + + ^ + 

188 I I ;^ I i I 131 I I I e I I 

^__„ + + „__^._._^. + + ^ ^ ^ 

155 I I / I I I 

+ + + --- + + 

+ 159 I . I I I I 

I + + + + + 

i-~-SCALAE OPS 15D \ I \ I | | 

+ + + + ___ + 

171 I I / I I I 

+ + + + + 

MIXED OPS -->■ 179 I I \ I I I 

+ + + + + 

COO I D I B I I 1 
+ — + — + — + — + 



FIGURE 17.1^ OPERATORS ARRANGED BY HEXADECIMAL CODE 
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FIGURE 17.2: OPERATORS ARRANGED BY FUNCTIONAL GROUP 



**001 ) 5005 C 7001 -t- 

4005 ] SOOZ? E 8005 3 

5001 ( 6001 I AOXl END 



FIGURE 17.3: SEPARATORS 
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exit to the APL 
does not define 
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operators format 
letter within a 
their external s 
change. The emu 
•box' functions ( 
370 CODE'). The 
be entered into 
opcode can only 
micro prog rammers 
a permanent usage 



supervisor (except 
the properties of 
e operators overstr 
and execute. The 
box are in the d 
ymbol and their de 
lator implements th 
see 'FUNCTIONS IMP 
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the workspace via 
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of the routines. 



for *.) . The emulator 

these operators. The 

uck wi th o are the new 

operators denoted by a 
evelopment stage. Both 
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LEMENTED IN APL AND IBM 
e an opcode that cannot 

the APL system. This 
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17.2 Separators 



The 

figure 17 
operator 
APL syst 
overstri k 
statement 
(this sta 
and 3 for 
of the s 
works Ilk 
1 ike a ve 
scalar, v 
type subs 
(Like 800 



codes for 
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is indexed, 
em and can 
ing the bra 

marker is 
tement)/ 2 

both stop 
ystem may u 
e 5005 exce 
ctor. in 
ector or a 
cript on a 
5 it cannot 



the various separators are 
5 separator is the bracket us 
(It is generated automatica 
not be entered into the wor 
cket with a minus.) The X in 
: for no stop or trace, 1 

for stop (before the next s 
and trace. APL functions whic 
se the separator 500D. This 
pt that it allows an array to 
other words, a 500D type subs 
n array has the same effect 
scalar, vector or the ravel or 

be typed by the user.) 



shown in 
ed when an 
1 1 y by the 
kspace by 
the end of 

for trace 
tatement ), 
h are part 

separator 
be indexed 
cript on a 
as a 5005 

an array. 



17.3 Special Operators 

A special operator has a 16 bit code ending in 11. The 
defined codes are: 



ONNN NNNN NNNN 0011 
INNN NNNN NNNN 0011 
UUUU UUUU UUUU 0111 
UUUU UUUU UUUO 1011 
WW WW WW 1111 



1 n 



a permanent function 
a temporary function 



go to N 

go to N 

make an 

perform an indirect operation 

secondary decode 



in 
'escape 



' emulator exit 



The purpose of the 'escape' operation is not defined by the 
emulator. In fact the system uses hexadecimal XX07 to flag 
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D=3 



an illegal character, where XX gives a representation of the 
character, and It uses NNNN TTF7 to flag an assignment to a 
stop or trace vector of a function. In this case NNNN Is 
the Internal name of the function and TT Is the Internal 
representation of S or T. The Indirect operation Is used by 
some APL system routines. If I Is the Indirect operation 
operator and N Is a name then Nl causes the emulator to get 
the low order eight bits of the address table entry for N 
and to use these eight bits as the low bits of a scalar 
operator. Thus If N Is an Integer address table Immediate 
with the value five then the emulator adds 18 to produce the 
scalar operator 1805. The secondary decode operation causes 
the emulator, to put the word: 

0001 0001 1011 1101 WW WW WW 1111 

on the stack. This will subsequently be treated like a 
'IIBD' operation and It will eventually call the IBM 370 
function corresponding to 'HDD*. The 370 function will 
find the W...11 In the low half of GPR9 and It can use It 
to select one of many sub-operations. 
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18. INTERNAL TEXT OF FUNCTIONS 



A function has the same Internal forn as a character 
vector, however, the syntax bits in the address table will 
distinguish between a variable and a function of 0, 1 or 2 
arguments. The internal form of a function Is: 

C DN HEAD BODY TAIL COMM NB C 

C Is the usual space management control word (see 'FREE 
SPACE'). D Is the descriptor of a character vector (OOSit) 
and N Is the internal name of the function. HEAD contains 
the half word Items: 

^5 T S K Z L R LI L2 ... LN 2 EZ 
where we have . . . 

M highest statement number 

T byte offset of TAIL from DN 

S system information, not used by the emulator 
(currently this Is 1 for a locked function, 2 for 
a function generated by quad and h for a function 
generated by execute) 

K kO + B times the the number of locals (decimal) 

Z name of the result or the number 1 

L name of the left argument or the number 1 

R name of the right argument of the number 1 

LI name of the I th local variable 

2 marker for the end of the locals list 

EZ marker for the end of statement 

Note that since the two low bits of a name are zero we can 
use both 1 and 2 to Indicate a non-name. The BODY has the 
form: 

SI El S2 E2 ... SM Ef.'i X EX 

where SK is the internal text of statement K (see 'INTERNAL 
TEXT OF STATEMENTS'). If the statement is a comment then SK 
is absent. EK marks the end of statement K. It contains 
the trace bit for statement K and the stop bit for statement 
K+1. X Is an 'Immediate go to 0'. Further details of EK 
and X are given In the 'OPERATORS AND SEPARATORS' section. 
The TAIL contains the byte offsets of EZ, El, E2, ... EM. as 
half v/ord Items. COMM contains system information such as 
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label names, the comments, and so on. The emulator is not 
concerned v/Ith the details of COMM. ND is the number of 
bytes in the HEAD, BODY, TAIL and COMM, Figure 18.1 
provides an example of a translated function. 



C=3 
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THE APL FUNCTION . .. 

Z <-- A F B;C;D;E 

Z <— A+B 

b COMMENT ON THIS LINE 

C <— D*E, 

Z;C;A 

VJITH A TRACE VECTOR OF 3 
AND A STOP VECTOR OF 1 1^ 
HAS INTERNAL FORM ... 

00000061 005tf007ii 0004001^6 OOOOOOUO 

006C0070 0078007C 00800081+ 0002 A021 

« 00781021 00707001 006C AQ01 A001 008U 

g 10310080 7001007C A031 007Q 6001007C 

-gS 6001006C A001 0003 AOOI OOIA 00260028 

003l|00U0 00010002 0U8B0000 0000005^1 

00000061 

WHERE WE HAVE UNDERLINED ALL END OF 
STATEMENT MARKERS INCLUDING EZ AND EX. 
WE NOTE THE FOLLOWING ... 

C 0000 0061 

DN 0051+ 0074 

M OOOli 

T 00it6 

S 0000 

K OOi+O 

Z=Z 006C 

L=A 0070 

R=B 0078 

L1=C 007C 

L2=D 0080 

L3 = E 0081* 

TAIL OOIA 0026 0028 0034 0040 

COMM 0001 0002 048B 0000 

NB 0000 0054 



FIGURE 18.1: INTERNAL FUNCTION TEXT EXAMPLE 
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loo. 



19. INTERNAL TEXT OF STATEriENTS 



19.1 Translation of Items 

The external form of a statement may contain comments, 
labels, names, constants, operators and separators. See 
'OPERATORS AND SEPARATORS' for the various 16 bit codes into 
which these items are translated. The remaining items are 
translated as follows: 

Comments? 

Comments should not occur in the body of a function. A 
^ comment statement should be replaced by a null statement; a 
null statement consists of an end of statement marker. The 
system may store the text of the comment in the COMM region 
of the function (see 'INTERNAL TEXT OF FUNCTIONS'). (The 
current system gets a block in free space and an internal 
name for each comment. These names are stored in COMM.) 

Labels: 

Labels should not occur in the body of a function. The 
system may store labels in the COMM region of the function. 
Also see 19.2. 

Names: 

An external name is represented by an internal name. An 
internal name is a 16 bit number ending with two zero bits. 
An external name has the same internal name irrespective of 
whether the name is the name of a local variable, a shared 
variable^ a global variable or a function. 

Constants : 

A constant may be scalar^ 16 bit or general. A constant is 

translated into a descriptor followed by the internal 

representation of the constant, according to the follov/ing 
bi t formats : 



Scalar: 


0000 


DDDD 


UUUU 


0010 


vv... 


16 Bit: 


MUUU 


DDDD 


UUUL 


0110 


vv... 


General : 


DDDD 


DDDD 


UUUL 


1010 


cccc ccuu vv. . 


or 


DDDD 


DDDD 


UUUL 


1010 


CCCC ccuu UUUU 



UUUU vv. 
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SO.O 



where U stands for unused and D..D is the descriptor bits 
described In 'VARIABLES IN FREE SPACE'. L is used to flar 
label constants (see 19.2). The first type of 
representation is used for integer scalars and real scalers 

i"^?f.^''f,^''^ '" '^^'^ ^''^ 32-bit integer format and reals are 
in IBM 370 6l|-bit floating point format. The 16 bit form is 
used for logical, character and short Integer scalars. In 
the latter case M is the sign bit. VV... is 16 bits long. 
As examples of this representation (in hexadecimal): 

0006 0001 logical 1 

0106 OOtjO integer 6h 

8106 FFCO integer -6U 

0U06 0099 character with internal code of 99 

« The general form is used for vectors. It could also be used 
■ror arrays although the current system does not do this. In 
this case VV... must begin on a full word boundary (hence 
f„^o^^° ^^'■'"^ shown) and VV... must be of the form shown in 
•VARIABLES IN FREE SPACE' . This implies that it must be 
padded out to a full word and should end with an element 
count. CCCC COCO is equal to four times N+2 where N is the 
number of words in VV... As an example, the three element 
vector Sh '6h ^ 102U has the internal representation 
lassumming that it does not begin on a full word boundary): 

510A OOIA 0000 0000 OOltO FFFF FFCO 0000 Oi^OO 0000 0003 



19.2 Use of Labels 

The emulator does not recognize the use of labels. If 
the program contains — >ALPHA and ALPHA is a label attached 
to statement 6k then ALPHA has the internal representation 
0116 OOltO. This is the internal representation of the short 
integer 6k with the L bit on. The emulator Ignores the L 
bit. The system may use the L bit when converting from 
internal to external form. The user may, of course, use 
labels in any legal manner. 



06/20/72 LPASN - IBM CONFIDENTIAL Page 19.2 



20. 370 REGISTERS AND 'GETV' 



Much of the information specifying the current status 
of the v;orkspace is maintained in the 370 registers. 
General register assignments are delineated in figures 20 1 
(GPR's) and 20.3 (FPR's). Register usage may vary a little 
during some of the microcode routines but the figures 
represent the normal state of affairs. 



20.1 'GETV 

Consider the execution of a statement such as 'Z<-L+R' 

g where Z, L^ and R are variables. The SCAN microcode will 

g scan this statement until it has detected the 'L+R'. At 

-^ this stage the stack registers (see 'THE STACK') v;i 1 1 

contain; 

GPRl = stack word for L 
GPR9 = stack v^ord for + 
GPR7 = stack word for R 
GPRE = null 

The SCAN microcode now calls the microcode which does dyadic 
operations. The dyadic operations microcode does a GETV on 
L (that is, it calls the GETV microcode with GPRl as input) 
and a GETV on R. GETV is used in all monadic and dyadic 
operations, in assignment and in subscripting. The results 
of GETV effect the operation of a large part of the emulator 
and a significant part of the system. GPR's 0-2 and 6-8 are 
devoted to the left and right arguments and are passed to 
GETV to fetch the first value and to change the variable 
stack v/ord into the appropriate register setup. Figure 20.2 
shows this setup. 

If the variable is real then the value will be In the 
corresponding floating point registers (FPRO or FPR6). 
Logical values will be setup as full words so that they may 
be treated like Integers, but for character variables only 
the rightmost byte of the value register Is defined. 

The PD DESCRIPTOR is the regular descriptor halfword 
(see 'VARIABLES IN FREE SPACE') with P-bits 5 and 6 (see 
'THE ADDRESS TABLE') or'ed into the first byte (which is why 
those bits must be 00 in the descriptor). These P-bits 
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c=o 



+-. + + + ^ 

10 I 1 I 2 I 3 I 

+ + ^ 

I I LEFT GETV REGISTERS | 

+— + I 

111 I 

+— + I 

12 1 I 

+ + __^ 

I 3 I EMULATOR IVORKSPACE BASE REGISTER | 

+ + ^ 

I h jABEN LINKAGE AND MISC | 

+ + ^ 

I 5 IMISC I 

+ + ^ 

I 6 IRIGHT GETV REGISTERS | 

+ — + , 

17 1 I 

+— + I 

I 8 I I 

+ + + 

I 9 {OPCODE {RESULT NAME { 

+ + _ ^^ + 

( A {LINKAGE AND MISC | 

+ + ^ 

{ B {PRESERVED FOR THE APL SYSTEM ( 

+ + ^ 

{ C {MISC {RESULT CURRENT ADDRESS { 

+ + - ^ 

I D {MASK AND MISC{ RESULT ELEMENT COUNT AND MISC { 

+ + ^ 

I E (NEXT STACK WORD j 

+ + ^ 

I F {RESULT BYTE {RESULT DESCB1{MASK AND CODE{ INDEX VALUE { 

+ + ^ 



FIGURE 20.1: NORMAL GPR ASSIGNMENTS 
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+ + + + + 

I I 1 I 2 I 5 I 

+ + — . + 

I0/6IUNDEFINED | 

+ + . + 

1 1/7 1 STACK VJORD FOR A VARIABLE OR IMMEDIATE | 

+ + + 

I2/8IUMDEFINED | 

+ + + 



FIGURE 20.2.1: GETV REGISTERS - INPUT 



+ + -. + + + 

I 1 1 ! 2 I 3 I 

+ + . . + 

I0/6IVALUE UNLESS IT IS REAL | 

+ + + 

I1/7IPD DESCRIPTOR |NAME | 

+ + + 

1 2/8 1 MASK I CURRENT ADDRESS | 

+ + + 



FIGURE 20.2.2: GETV REGISTERS - OUTPUT 
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+-. + + + + 

I I 1 I 2 I 3 I 

+ + + 

I ILEFT VALUE IF IT IS REAL | 

+ — + I 

111 I 

+ + + 

I 2 ISWITCHES lUfJALLOCATED BLOCK ADDRESS (FREEU) | 
+ + + 

13 1 k |UNUSED=00 |NEXT AVAILABLE NAME | 
+ + . + 

I k I RESULT VALUE IF REAL, LINKAGE AND MISC I 

+— + I 

15 1 I 

« I 6 jRIGHT VALUE IF IT IS REAL | 

+— + I 

17 1 I 

+ + + 



FIGURE 20.3: NORMAL FPR ASSIGNMENTS 



DO 



BIT RESERVED FOR THE SYSTEM 

1 ATTN - STOP AT STATEMENT END 

2 Y SVilTCH* 

3 Z SV/ITCH* (CURRENTLY UNUSED) 
k QUANTUM END DESIRED 

5 DOING SERVICE FUNCTION 

6 INDEX ORIGIN 

7 SET TO 1 BY TIDY (OTHERWISE UNUSED) 

* USUALLY 0; MAY BE TEMPORARILY 
SET TO 1 BY THE MICROCODE 
(EG, SEE THE GETN ROUTINE) 



FIGURE 20. ft: SWITCH BIT ASSIGNMENTS 
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identify addressed value or immediate value and temporary or 
permanent states. A stack immediate is given P-bits 11; the 
'permanent' state is set so that the microcode will not 
attempt to release the name of the variable after It is used 
in the operation. Thus one can count on the NAME being good 
only if the variable is not an immediate. There is no way 
to distinguish, between stack immedlates and address table 
Immediates once they have been through GETV. 

GETV will set the current address to point to the 
beginning of the value portion of the variable block (of the 
value block in the case of synonyms). In later stages of 
executing an operator this Is usually the address of the 
element following the element currently given in the 
regi sters. 

The MASK is not actually setup by GETV; other 
processing microcode will set It up If a logical vector is 
being used. 

The GETV function Is available to the APL system 
through the APLGETV macro. 



20.2 Other Comments 

Two bytes (GPRD.O and GPRF.2) are marked as being masks 
in figure 20.1. Both refer to a mask for a logical vector 
result. Some operators will use one byte, others will use 
the alternative byte. Never will both be In use as masks 
and frequently neither will be. GPRF.2 also serves as the 
370 function return code byte (see 'FUNCTIONS IMPLEMENTED IN 
APL AND IBM 370 CODE' ). 

The result byte (GPRF.O) is used to build up a byte of 
values prior to storing during some of the cases with 
logical vector results. The last byte of the result 
descriptor is usually kept In GPRF.l. The 0-origin index 
(or its ceiling If real) Is kept In GPRF.3 during execution 
of Indexable operators; the default value is given If an 
explicit value v^;as not specified. 

Normally the first byte of QEND contains the SVnTCHES 
byte. When the APL microcode has control, hov/ever, they are 
maintained in the first byte of FPR2. The individual switch 
assignments are given In figure 20. U. FPR2 is also 
described in 'FREE SPACE' (FREEU) and in 'THE ADDRESS TABLE' 
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(NEXT AVAILABLE NAME) 



D=0 
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21. APL SYSTEM/APL EMULATOR INTERFACE 



The most important function of the emulator is to 
execute APL statements. The emulator also provides service 
functions which can be used by the software to assist the 
translator, the 370 functions and the error recovery 
procedure. The execution of APL statements and the service 
functions are initiated by IBM 370 assembler language macro 
Instructions. All such macros rely on a single instruction 
which has been added to the 370 instruction set. The APL 
Emulator Call (APLEC) is an RR instruction with opcode OB. 
It is similar to SVC in that the immediate byte gives a call 
code and certain registers may be used for arguments and 
^ results. It is dissimilar in that, additionally, GPR3 must 
^ properly address a workspace or a specification exception 
-S will occur. We pointed out earlier that the APL emulator 
v/orks in an environment consisting of a workspace and the 
370 registers. This environment is assumed throughout this 
report. Thus v;hen we say, for example, that APLSCAH will 
cause scanning and execution of the v/orkspace we are 
assuming that GPR3 addresses a workspace as described 
earlier, that GPRl, GPR9, GPR7 and GPRE are properly set up 
as stack registers (see 'THE STACK') and so on. Figure 21.1 
summarizes the APL macros and figure 21,2 gives the BAL 
definitions. The remainder of this section discusses each 
macro in the order given in figure 21,1. 'Exceptions' may 
be real program exceptions (Specification, Data) or an APL 
error return signaled by a condition code of 1 and an error 
code in GPRS (all others). 



APL FIND 

A block of free space of the indicated number of bytes will 
be found. Its space management control v/ords and the N 
portion of its DN word will be completed. It will be 
classified as a temporary variable v/ith an addressed value 
and its address table entry will be completed. The address 
of byte of its DN v/ord will be returned in GPRlj. Note 
that the number of bytes must include the 12 necessary for 
the DN and two control words. 

Exceptions: Specification 

Workspace Full 
Address Table/Stack Full 
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XXXX ARGUMENT 



RESULT 



FUNCTION 






FIND 

FREE 

FRIF 

NAME 

UNAM 

TIDY 

SCAN 

GETV 

GETN 

RTN 

SRTN 

RESM 

DIAG 



R5=bytes 

R5=name 

R5=name 

none 

R5=name 

none 

none 

see text 

see text 

none 

none 

none 

see text 



Rii=DN addr 
none 
none 
Rit=name 
none 
none 
none 

see text 
see text 
not appl i c 
not appl ic 
not appl Ic 
see text 



find a free space block 
free an i tern 

free an Item if temporary 
provide an unused name 
release an obsolete name 
perform garbage collection 
scan/execute a v/orkspace 
get a stacked variable 
get a variable number 
normal 370 function return 
special 370 function return 
resume Interrupted workspace 
diagnostic function 



FIGURE 21.1: SUMMARY OF THE VARIOUS APLXXXX MACROS 
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D=0 





MACRO 


&L 


APLEC &CODE 


&L 


DC Y(X'0B00'+&CODE) 




MEND 




MACRO 


&L 


APLFIMD 


&L 


APLEC X'63' 




MEND 




MACRO 


&L 


APLFREE 


&L 


APLEC X'83' 




MEND 




MACRO 


&L 


APLFRIF 


&L 


APLEC X'A3' 




MEND 




MACRO 


&L 


APLNAME 


&L 


APLEC X'23' 




MEND 




MACRO 


&L 


APLUNAM 


&L 


APLEC X'ti3' 




MEND 




MACRO 


&L 


APLTIDY 


&L 


APLEC X'03' 




MEND 




MACRO 


&L 


APLSCAN 


&L 


APLEC X'OO' 




MEND 



FIGURE 21.2.1: BAL DEFINITIONS FOR APL MACROS 
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C=Q 



&L 


APLGETV &VAR 




LCLA 


&VARC 


&VARC 


SETA 


X'02' 




AIF 


C&VAR' EQ 'LEFT').VAROK 


&VARC 


SETA 


X'68' 




AIF 


C&VAR' EQ 'RIGHT' ).VAROK 




MNOTE 


'BAD VARIABLE SPECIFICATI 


.VAROK 


ANOP 




&L 


LA 


5,&VARC 




APLEC 


X'D3' 




MEND 






MACRO 




&L 


APLRTN 


&L 


APLEC 
MEND 

MACRO 


X'Ol' 


&L 


APLSRTN 


&L 


APLEC 
MEND 

MACRO 


X'02' 


&L 


APLRESM 


&L 


APLEC 

MEND 

MACRO 


X'02' 


&L 


APLDIAG 


&L 


APLEC 

MEND 


X'E3' 



- RIGHT ASSUMED' 



FIGURE 21.2,2: BAL DEFINITIONS FOR APL MACROS 
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&L 

&VARC 

&VARC 



.VAROK 
&ENTRYC 

&ENTRYC 



.ENTRYOK 
&TYPEC 

&TYPEC 

&TYPEC 



.TYPEOK 

&ARG 

&L 



MACRO 

APLGETN &VAR,&ENTRY,&TYPE 

LCLA &VARC,&ENTRYC,&TYPEC,&ARG 

X'02' 

C&VAR' EQ 'LEFT'). VAROK 

X'68' 

C&VAR' EQ 'RIGHT'). VAROK 

•BAD VARIABLE SPECIFICATION - RIGHT ASSUMED' 

C&ENTRY' EQ ' FETCH '). ENTRYOK 

1 

('SENTRY' EQ ' I N I T ' ) . ENTRYOK 

2 

C&ENTRY' EQ ' CVT' ). ENTRYOK 

'BAD ENTRY SPECIFICATION - CVT ASSUMMED' 

C&TYPE' EQ 'LOG'). TYPEOK 



SETA 

AIF 

SETA 

AIF 

MNOTE 

AIF 

SETA 

AIF 

SETA 

AIF 

MNOTE 

AIF 

SETA 

AIF 

SETA 

AIF 

SETA 

AIF 

MNOTE 

ANOP 

SETA 

LA 

APLEC 

MEND 



C&TYPE' 

3 

C&TYPE' 

2 

C&TYPE' 



EQ 

EQ 



•INT'). TYPEOK 
'REAL'). TYPEOK 



EQ 'ASIS'). TYPEOK 



'BAD TYPE SPECIFICATION -ASIS ASSUMMED' 

&VARC + 2 56*(&ENTRYC + ii*&TYPEC) 

5,&ARG 

X'C3' 



FIGURE 21.2.3: BAL DEFINITIONS FOR APL MACROS 
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APLFREE 

This releases the free space associated v/ith the named item 
unless it is an immediate and, in the case of temporaries, 
releases the name as well. 

Exceptions: Specification 



APLFRIF 

This performs an APLFREE if the named item is a temporary, 
if it is a permanent then nothing is done. 

^ Exceptions: Specification 



ODJ 



A PL NAME 

The next available name v/i 1 1 be removed from the unused list 
and returned in the right half word of GPRi+; the left half 
word is unpredictable. The address table will be unchanged. 

Exceptions: Specification 

Address Table/Stack Full 



APLUNAM 

The specified name will be restored to the list of unused 
names and the address table so marked. 

Exceptions: Specification 
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APLTIDY 

A garbage collection will be done and all relevant pointers 
(FREED, various address table and stack entries, etc) 
corrected. The GPR variable addresses (GPR2, 8 and C) v;i 1 1 
also be maintained if accurate, but they will be scratched 
if not. For example the 370 dominoe function may do an 
APLTIDY, If it is the dyadic case both the left and right 
variable GPR's will be maintained, but if it is the monadic 
case the left variable GPR's are unpredictable. 



Exceptions : 



Specif i cation 

Data (see 'DEBUGGING AIDS') 



c=o 



APLSCAN 



Scanning and execution of the vjorkspace will commence at the 
address specified by the control v/ord 'NEXTIMST'. 



Exceptions : 



Speci f i cation 
V/orkspace Ful 1 
Stop Vector Request 
Value Error 



Etc. -- See the emulator routine 'ABEN' for a 
complete list of error exits and their codes. 



APLGETV 



LEFT 
RIGHT 



This gets a variable from the stack and sets it up for 
processing (see '370 REGISTERS AND 'GETV'). For the left 
(right) variable GPRl (7) must contain the stack word; the 
macro v/ill setup GPRO-2 (6-8). 



Exceptions 



Speci f i cat ion 
Val ue 
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APLGETN LEFT , I MIT ^OG 

RIGHT FETCH INT 
CVT REAL 
AS IS 

This gets a number from a variable v;hich has been set up by 
the emulator or APLGETV. The first call should be v/i th 
'INIT'; this v;ill return the element count in GPRlj as well 
as the first number. Subsequent calls should be v/ith 
'FETCH' for each additional element. Cyclic fetching will 
be done automatically if the element count is one. If the 
user does his own initialization and fetching 'CVT' may be 
used for conversion only. In any case one requests the type 
of output desired: logical/ integer, real, or 'ASIS', i.e., 
no conversion. GPRU v;i 1 1 be altered only by the 'INIT' 
S option. 



ion 



Exceptions: Specification 

Domain Error 
Range Error 



APLRTN 

This returns control from a normal 370 function to the APL 
emulator. 



Exceptions: Specification 



APLSRTN 



This returns control from a special 370 function to the APL 
emulator. 

Exceptions: Specification 
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APLRESM 

This returns control from an interrupt or quantum end 
condition to the APL emulator. 

Exceptions: Specification 



APLDIAG 

This macro Is for use only by mi croprogrammers. It is a 
debugging and diagnostic aid. It is documented only in the 
source listings for the APLDIAG decode point in the SERV 
microcode routine. 
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22. STATEMENT SCAN AND SYNTAX ANALYSIS 



At the beginning of the execution of an APL statement 
the stack contains 

U N U E prior 

where U denotes undefined, N denotes null, E denotes empty 
and 'prior' denotes whatever v/as on the stactc before the 
current function vjas entered. The SCAN routine changes the 
stack to 

U N E E prior 

[ I — ] 

(oo) and then does the following: 



LOOP: Get the next half word from the APL statement. 
Increase NEXT INST by tv/o. 
Let H denote the half v;ord just read. 
Branch on the tv/o lov/ order bits of H. 

BITS=00: H is a name. 

Get its address table entry. 
Put it on the stack. 

BITS=01: H is an operator or separator. 
Put it on the stack. 

BITS=10: H begins a literal. 

If it is a 16 bit literal, then ... 

P ut it on the stack as a stack irmiediate. 
Otherwi se . . . 

Get space in free space. 

Copy the constant. 

Put its S-bits, P-blts and name on the stack. 

BITS=11: H is an escape case. 

These cases cause an immediate action. No further 
scanning is done. See 'OPERATORS AND SEPARATORS' 
for a description of the escape cases. 



Having put the item on the stack (and thus erasing the 
undefined item at the top of the stack), let ST denote the 
syntax bits of the top item on the stack (syntactical types 
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are shov/n in figure 22.2) and let SM denote the syntax bits 
of the next-to-top item. If DTAB<ST;SK> (see figure 22.1) 
is zero then push the contents of the stack as described in 
'THE STACK' and go to LOOP. Otherwise do the action 
specified in figure 22.3. 

End of statement processing (action 10) includes 
checking to see if printing is required and checking for 
stop/ trace, attention and quantum end. If there is a 
temporary on the stack and no print or trace is requested 
and the last action was an assignment, then free the name 
and space used by the variable (unless it is a stack 
immediate). 

The system uses syntax type F for group names. The 
^ emulator should never encounter these names, but if they do 
occur due to a user error then the emulator gives a syntax 
error. 

Some of the dynamic properties of APL can give rise to 
some unusual problems, in particular a change of the syntax 
type of a variable may produce an error. The emulator 
insists on the following rule: If a name has a syntax type 
other than 2 then it must have a descriptor of type 
character. As an example, functions (see 'INTERNAL TEXT OF 
FUNCTIONS') are of type character. The GETV microcode 
checks the syntax of all character items and it gives a 
syntax error if the syntax type is not 2. Consider the 
execution of the statement 'Z< — F+A', v;here F is a niladic 
function and A is a variable. The emulator puts entries for 
'null', 'variable A', '+', and 'F' on the stack and then it 
calls F. If the function F executes correctly and it has a 
result then the emulator will attempt to add A to the result 
of F. The addition will cause the emulator to do a GETV of 
A. If A is no longer a variable then a syntax error 
results. The syntax of A could have changed because A v/as 
made into a shared variable, or because the user stopped the 
execution of F and changed A Into a function or a group 
name. The address table entry for a shared variable does 
not point directly to the value of the variable. The method 
of storing shared variables is not defined by the emulator, 
but the block v;hich the address table points to must be of 
type character even if the value is arithmetic. 
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ST 



SN 

1 
2 
3 
k 
5 
6 
7 




C=Q 



FIGURE 22.1: DTAB<ST;SN> - THE SYNTAX DECISION TABLE 






null 


1 


oper 


2 


van 


3 


f unc 


k 


rlgh 


5 


left 


6 


semi 


7 


ass 1 


8 


righ 


9 


f unc 


A 


end 


B 


func 


C 


quad 


F 


ille 



a tor 

able 

tion of tvio arguments 

t parenthesis or right subscript bracket 

parenthesis or left bracket 
-colon 
gnment 

t indexed-operator bracket 
tion of no agruments 
of statement 
tion of one argument 
, quote-quad or shared variable 
gal (group) 



FIGURE 22.2: SYNTACTICAL TYPES 
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Continue the scan. 

1 Give a syntax error. 

2 Do a dyadic operation. The stack is left operand, 
operator, right operand. 

3 Check for reduction and, if so, do it. Check for 
inner or outer product and, if so, encode the 
three operators into a single word (for example, 
+ .X is encoded as the . operator v/ith + and x in 
the low half of the word). If neither reduction 
nor product then do action number h, 

k The stack is operator, operator, operand. 

Subtract two from NEXTIMST and ignore the top 

stack v/ord (the first operator). Do a monadic 

operation. 

5a The stack is function, ... Change it to 

^ undefined, function, undefined, ... Do action 5c. 

g 5b The stack is function, argument, ... Change it to 

-^ undefined, function, argument, ... Do action 5c. 

5c The stack is Al F A2, U F Al, or U F U where U is 
undefined, F is a function and AN is a function 
argument. Do a function call. 

6 Go to the subscript microcode. 

7 Go to the assignment microcode. 

8 If the top stack item is a '(' then erase it and 
the corresponding ')' and pull the stack up. The 
alternative is that the item is a left 
subscripting bracket in which case merely continue 
the scan. 

9 Change syntax type 8 to type if and continue the 
scan. 

10 Do the end of statement processing. 

11 Call the APL supervisor shared variable routine. 

12 The top stack item is an indexed operator. Remove 
the index and brackets from the stack. Encode the 
Index In 9 bits and store it in the stack word for 
the operator. Then continue the scan. 

13 Mark the left bracket as a left bracket with an 
assignment arrow and continue the scan. 

Ik Put an empty subscript marker (G201 or 6205) on 

the stack and continue the scan. 



FIGURE 22.3: TABLE OF ACTIONS SPECIFIED BY DTAB 
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23. FUNCTION INVOCATION 



This section describes hov/ function call and return 
affect the contents of the stack and it shows how the state 
indication can be found. The. state indication can be 
displayed by use of the APL command )SI. 



23.1 Function Call 

Suppose the emulator is executing the statement 

c=^ B <-- (P F Q) + R 
(ss) 

.§ where P, Q, R are variables and F is a function of tv/o 

arguments with the header information 

VI <— V2 F V3;Vfi;V5;V6 

At the point where the SCAN microcode has read the P then 
the stack wi 1 1 be 

P F Q ) + R nul 1 prior 

where 'prior' denotes whatever was on the stack at the 
beginning of execution of this statement. P F Q and ) are 
actually in the stack registers (see 'THE STACK') and '+' is 
the last item to be put into the memory stack. Vihen v/e say 
that 'P' is on the stack, we of course refer to a full word 
Item which contains the syntax bits and internal name of P 
according to the format described in 'THE STACK'. The 
microcode uses the header information of F, and it changes 
the stack contents to 

U null E E K L A6 W6 ... Al Wl C I ) + R null prior 

The top four items are in the stack registers and K is the 
last Item in the memory stack. U is undefined, E is empty 
and the items ) + R null prior are unchanged. 

K = 0000 1111 uuuu uuuu kkkk kkkk kkkk kkOO 

v/here u = undefined and kk ... kkOO = decimal UO + 8 
times the number of local variables (In this case there 
are three local variables and kO + 2k is 6U decimal or 
kO hexadecimal so the low half of K is OOUO.) 
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ID.O. 



L = 0000 1111 uuuu uuuu 0000 0000 0000 0010 

(This is a special case of \in and it marks the end of 
the Wl Al Vi2 ... sequence.) 

An = address table entry for variable Vn 

V^n = 0010 1111 uuuu uuuu wwv/v/ wv/wv/ vrvjvm wwOO 

where ww . . , wwOO = internal name of variable Vn 

C - 0000 1010 uuuu uuuu cccc cccc cccc ccOO 

where cc ... ccOO = internal name of function v/hich 
contains the statement which calls F 

I = 0000 1111 uuuu uuuu iiii iili iili ilii 
^ where ii ... ii = offset of next byte of calling 

statement, which in this example is the offset of the ( 



The extension to functions v/ith a greater or less 
number of local varibles should be obvious. For functions 
with no result then the Al and Wl items still appear but Al 
shows 27 ... (hexadecimal) and Vil shows OFUUOOOl. Similarly 
v/ith A2/ W2 for monadic and nl ladle functions and v/i th A3, 
V/3 for nl ladle functions. 

If Vn Is the name of an I tern which is In free space 
then An contains the address of that item. Let x denote the 
address of the word An; let y denote the address In the low 
2k bits of An. Before function call, the half word at 
location y+2 contains the Internal name of Vn. During 
function call, we change this half word to x minus GPR3. 
This change of the contents of y Is necessary for correct 
operation of workspace relocation and garbage collection. 

The function call microcode, sets the address table 
entries of VI, V2, V3, VU, ... to no value and then It gives 
V2 the value P and it gives V3 the value Q. If P is a large 
vector or array the 'giving' V2 the value P means that P and 
V2 are made into synonyms. The emulator does, of course, 
process correctly those complicated cases in which P or Q or 
both P and Q have the same name as VI or any other local 
variable. The statement: 

U <— X G X 

v/here G has the header 

X <-- A G B 
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torn) 



Illustrates one of the more complex cases. 



23.2 Temporary Functions 

In APL/360 the user can type a single statement v;hlch 
receives Immediate execution. The emulator requires that 
such single statements should be converted (by the 
translator part of the APL system) into a function. If the 
user types the statement 

A <— B + C 

^ then the translator supplies a head and a tail and the 
emulator actually sees an internal representation of a 
nl ladle function having a temporary name. We v/i 1 1 refer to 
this construct as a temporary function. 

There are two other occasions when temporary functions 
are used. A statement such as 

P <— Q + e X 

where X is a character string v/ith value 'A< — B+C' and je is 
the execute operator, requires that the character string X 
should be treated as an APL expression. This is implemented 
as follov/s: V/hen the emulator sees the execute operator 
then It calls the APL system. The system builds a temporary 
function, t, like the one above and returns the name of t to 
the emulator. The emulator now behaves as though the 
statement had been written 

P <— Q + t 

and it calls t using the mechanism described In the previous 
section. Quad input is also implemented in this v/ay. 

The use of temporary functions is a simple but powerful 
v;ay of unifying several different concepts In APL; for 
example multiple nested execute operations are easily 
handled In this v;ay. 



23.3 Exit From Permanent Functions 
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Consider a function F which contains M statements. The 
program v/ill exit from F if any of the following statements 
occur: 

--> 

— > Integer where the integer Is less than 1 or 

greater than N 
— > expression where the expression reduces to an 

integer >N or <1 
Execution of statement N with no branch 

The first case causes the emulator to signal a syntax error; 

the system should trap the error return and do the 

appropriate action. The third case is similar to the second 

case. The fourth case is also similar to the second case 

M because the translator always Includes a fictitious ' — >0' 

^ after statement N. As cases tv/o, three, and four are being 

-S^ executed the stack contains 

— > V E E K L ... 

where Visa constant or a variable, E denotes empty, and K 
L ... denotes the sequence described In 'Function Call'. 
The first four I terns are in the stack registers and the K L 
... are in memory. Assuming that V is a scalar (or a 
vector) and assuming that V {or the first element of V) is 
an integer less than one or greater than N, then the 
emulator frees the space used by V, if necessary, and then 
it does a function return. 



23. k Function Return 

The contents of the stack registers can be ignored, so 
using the example of 23.1 the stack is 

K L A6 W6 ... Al Va C 1 ) + R null prior 

The emulator uses the value of K as an offset on the current 
stack address and picks up C and I. V/e said In section 23.1 
that C begins with a zero bit; however, C may now begin with 
zero or 1. After C has been put on the stack then the user 
may have suspended execution and then erased the function 
named by C. Obviously it would be dangerous to return to a 
non-existent function so when the erasure occurs then the 
APL system changes the first bit of C to 1, and on detecting 
this case the emulator takes an 'ERASE' type exit. If the 
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first bit of C Is zero then function return continues. 

The emulator nov/ goes through the stack and does the 
f o 1 1 ow I ng : 

a) Get IVn and hence get the name of Vn 

b) If Vn has a value in free space then release this space 

c) Get An and store it In the address table entry for Vn 

d) If An points to an address in free space then plant Vn at 
that address 

There are two variations on this theme. Before doing steps 

M a) through d), save the current value of VI, If any, because 

P this is the result. Also, if Wn is an odd number then 

-^ Ignore subsequent steps because this is an empty slot 

corresponding to a no argument or no result. 

The emulator nov/ checks that the function has a result, 
and It gives the result the temporary name t, it sets the 
stack (and stack registers) to 

U t U ) + R Null prior 

restores MEXTINST (from I) and FUMCTION (from L) and returns 
to the SCAN microcode routine. If the function has no 
result then It checks that the top of the stack Is null and 
that the next Instruction Is an end of statement. 



23.5 Return From a Temporary Function 

The return from a quad input or an execute temporary 
function requires special action. The APL system traps this 
case by use of the 'stop' bit in the end of statement 
marker. Let us now consider temporary functions resulting 
from single statements. The operator ' — >' with no argument 
produces a syntax error which the APL system also traps. 

There are tvio other cases, namely 

(1) — > n 

(2) successful execution of the statement with no branch 
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n stands for a scalar integer. Statements of the form '--> 
expression' are either in error or reduce to case (1). 

Consider case (1). This case has arisen because the 

user had typed ' — > n'; at the beginning of the execution of 

this statement, the stack was either empty or the head of 
the stack was a STOP WORD (see 23.5). After executing the 

statement, the emulator frees the temporary function. At 

this point the stack registers are irrelevant and the stack 
in memory has the form 

i\ * • • . 

The two low order bits of K may be 01, 10, or 11. If the 

bits are 10 then this is the end of stack marker and the 

^ emulator takes a normal end of execution exit. If the bits 

^ are 01 then the bits were originally 11, corresponding to a 

-S stopped function, but the function has been erased; in this 

case the emulator takes an 'EMPTY' exit. If the bits are 11 

then this requires the restart of a stopped function. K 

contains the name of the stopped function. The emulator 

puts this name into the control v/ord 'FUflCTION' and nov; does 

a normal 'go to' in the context of that function. 

In case (2), that is successful execution of the 

statement with no branch, then the emulator takes a normal 

exit from the emulator and does not free the space used by 
the function. 



23.6 Status Indication 

The execution of an APL program can be terminated in 
several ways. Typical examples are (a) the program 
completes successfully or (b) the emulator detects an error 
or an exceptional condition such as 'workspace full' or (c) 
the emulator detects a stop bit at the beginning of a 
statement or (d) the user gives an attention. In all of 
these cases the current status is determined by the control 
words FUNCTION, NEXTINST, and TSADDR, together with the 
contents of the stack. The status can be displayed by use 
of the APL commands )SI and )SIV. In this section we 
describe how this status is determined. 

In this section the word stack will refer to the stack 
in memory; the contents of the stack registers are 
irrelevant. I terns are placed on the stack in one of three 
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ways: (1) The SCAN microprogram may use the stack for 
intermediate working. (2) The function call microcode saves 
certain information which is described in a previous 
section. (3) If an error or stop Is encountered then the 
APL system puts a stop word on the stack. Let us denote 
these three types of stack information as 'SCAN BLOCK', 
'CALL BLOCK',, and 'STOP WORD'-. At the beginning of 
execution in a clear workspace, the stack contains just one 
word which Is the 'BEGIN STACK' word. 

Suppose the user types In a statement which the system 
embeds in a temporary function Tl. Suppose Tl calls 
function F, statement 8 of F calls G and G has an error at 
statement 5. Suppose the user now types In another 
statement, which the system embeds In a temporary function 
« T2. Suppose T2 calls function H and H has an error at 
statement 3. The stack contents and status are 



op. 



TSADDR — > 



Stack Comment Status 

STOP WORD H<3> * 

CALL BLOCK T2 calls H 

SCAN BLOCK T<1> 

STOP WORD G<5> * 

CALL BLOCK F calls G F<8> 

SCAN BLOCK F<8> 

CALL BLOCK Tl calls F 

SCAN BLOCK T1<1> 

BEGIN STACK 

A STOP WORD has the form 

STOP = 0000 nil Ml! Mil NNNN NNNN NNNN NNPl 

where NN...NNOO gives the internal name of the function In 
which the statement occurred and I II... MM gives the 
statement number. P Is usually one but it gets set to zero 
if the function NN...NNOO is erased or edited in a way which 
damages the stack. If H has the internal name 007C then a 
stop at statement 3 v/ould give the STOP WORD 0803007F 
hexadecimal. A SCAN BLOCK can contain any I tern which the 
SCAN microprogram will push Into the stack. All of these 
Items are single v/ords of the form 

where SSSS can be 0000 through 0111. If SSSS is 0000 then 
the next four bits are always 0111 so that this case (which 
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is the null item) has the form 
NULL = 0000 0111 

The CALL BLOCK is described in a previous section, but 
notice that it alv^ays begins with a word of the form (item K 
of section 23.1) 

CALL = 0000 1111 .... 00 

Finally the BEGIN STACK word has the form 

BEGIN = 0000 luuu u... uulO 

v/here u stands for undefined; In practice the BEGIN STACK 
^ word is 08000002 hexadecimal. 



oo 



If the system is going to analyze the stack then it 
must start at the top of the stack which Is (contents of 
TSADR)+U. If the emulator has just done a 'successful 
completion' exit then the top of the stack will be a STOP 
l-^ORD or the BEGIN STACK word. If the emulator has just 
encountered a stop bit in a begin of statement then the top 
of the stack will be a CALL BLOCK. The system will then 
place a STOP WORD on the stack. If the emulator has just 
encountered an error then the top of the stack may be (a) 
part of a SCAN BLOCK or (b) the beginning of a CALL BLOCK or 
(c) a STOP WORD or (d) the BEGIN STACK word. The system 
can analyze the situation in the follov/ing v^ay: If the top 
of stack word begins with 00001 then it is a CALL WORD or 
STOP WORD or BEGIN STACK word. Otherwise it is part of a 
SCAN BLOCK. If the top of the stack is part of a SCAN BLOCK 
then It will erase this word (by increasing TSADR by k) and 
repeat the analysis. When this analysis is complete then 
the top of the stack word has the form 

0000 1 ..xn 

where xn=00 indicates a CALL BLOCK, 10 indicates the BEGIN 
STACK word, and 01 or 11 indicates a STOP WORD. If the top 
of the stack is a CALL BLOCK, then the system will add a 
STOP WORD to the stack; it will form this word from the 
contents of FUNCTION and NEXT INST. 

To summarize the situation, starting at the top of the 
stack It is possible to distinguish STOP WORDs, beginning of 
CALL BLOCK words, the BEGIN STACK word and v;ords which 
belong to SCAN BLOCKs. Having recognized a STOP l/ORD it Is 
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possible to determine the statement number and function 
name. Having recognized a beginning of a CALL BLOCK it is 
possible to skip over that BLOCK or to find the name of the 
calling function or to find the names and old values of all 
local variables. 



t=o 
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2k. EXAMPLE WORKSPACE 



In this section we provide a workspace which has 
intentionally been setup to produce an error, thus supplying 
an example with Information on the stacl<, shadowed variables 
and so on. Figure 214.I gives the console listing for the 
example, figure 2U.2 delineates several key Items and figure 
2*1.3 gives a dump of the workspace. 

In figure 2'*. 2 we see that the workspace was loaded and 

the GO function executed. A 'domain error' occurred and 

then we see 'DUMP NO 00000001'. Normally the APL system 

would not produce a dump, but this was run using a version 

M of the system especially coded to provide system and 

g microcode debugging Information. The remainder of the 

-S console listing Is as would occur with the standard APL 

system. It shows the status indicators, the shadowed 

variables, function definitions and current variable values. 

Figure 24.2 gives the symbols in sequence by both 
external name and by internal name as well as several other 
Items. We note here that on the dump the displayed GPR's 
are those active when the system provided the dump; the 
GPR's of Interest to us are stored In locations 270A8 to 
270E'i In the sequence GPR4, ..., GPRF, GPRO, ..., GPR3 (see 
DEBUGGING AIDS'). Thus GPR3 is found to be 273A0. Since 
A' has Internal name 0070 Its address table entry is at 
273A0 + 70 or 27£j10. 

The beginning of free space was calculated as follows: 
FREES (at 27390) Is C70. This is a displacement so we add 
GPRS (273A0) to give 28010. Since FREES points to the first 
real block In free space, the dummy block Is the preceeding 
word (at 2700C). 

The stack in the workspace dump (figure 2'f.3) shows a 
temporary function calling GO and GO calling F which then 
calls G. The dump is worth studying In detail to find such 
things as a shadowed AP vector (P In GO) and a synonym chain 
linking an array (A) and a vector (shadowed Q) . 
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)LOAD EXWKSP 
SAVED 13.59.36 06/06/72 



GO 

DOMAIN ERROR 
DUMP NO 00000001 
GCl] X^U+2 
A 



)SIV 
GLll * Q V X 

PCs] R Q P B 

G0121 



vffOCDJv 

V GO 
[1] R-^Z 3pP^;9 
[2] R F(i3)o.xt3 

V 



VFCD3V 

7 Z-<->5 F S;P;a;i? 
[1] Q-^^A 
[2] i?-*-^+B 
[3] Z-s-^CC'Z' ;3;] 

V 



VGCDDV 

Cl] X-«-t/+2 
V 



FIGURE 2U.1.1: EXAMPLE WORKSPACE CONSOLE LISTING 
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c=o 







1 

H 
7 


j4 

2 3 

5 6 

8 g 


1 
2 
3 


B 

2 3 

4 6 
6 9 



R 



U 



R 
2 4 
6 9 
10 m- 



6 
12 

18 



U 



FIGURE 2It.l.2: EXAMPLE WORKSPACE CONSOLE LISTING 



06/20/72 



LPASN - IBM CONFIDENTIAL 



Page 21;. 3 



0=3 



EXTERNAL 


INTERNAL 


ENTRY 


VALUE OR 


NAME 


NAME 


ADDRESS 


ADDRESS 


A 


0070 


27410 


36794 


B 


0078 


27418 


367A8 


F 


0071* 


27414 


28034 


G 


0088 


27428 


2809C 


GO 


009it 


27434 


280E8 


P 


007C 


2741C 


NO VALUE 


Q 


0080 


27420 


NO VALUE 


R 


008** 


27424 


36754 


U 


0090 


27430 


IMEDIATE 


X 


008C 


2742C 


NO VALUE 


Z 


006C 


2740C 


NO VALUE 


z 


006C 


2740C 


NO VALUE 


A 


0070 


27410 


36794 


F 


0074 


27414 


28034 


B 


0078 


27418 


367A8 


P 


007C 


2741C 


NO VALUE 


Q 


0080 


27420 


NO VALUE 


R 


0084 


27424 


36754 


G 


0088 


27428 


2809C 


X 


008C 


2742C 


NO VALUE 


U 


0090 


27430 


IMEDIATE 


GO 


0094 


27434 


280E8 



•x 



I vl 



ITEM 

GPR3 
GPRB 
TSADR 
NEXTINST 
FUNCTION 
BNDATS 
FREE SPACE 
FREE SPACE 



BEGIN 
END 



ADDRESS 


VALUE 




270E0 


273A0 


(SEE TEXT) 


270C0 


27000 


(SEE TEXT) 


27404 


27F4C 




27400 


280BC 




273FC 


0088 




27408 


27C08 




27390 


2800C 


(CALCULATED) 


27394 


367FC 


(CALCULATED) 



FIGURE 24.2: EXAMPLE WORKSPACE ITEMS 
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mm 



^ GPR = 00000000 OOOIUOFI 00000037 00000000 00016UDC 00000008 FFFD9002 06010002 
m GPR 8 = 20036758 10211021 OOOHiOUC OOOlfjlFU 00013090 00027000 000135B0 5001376A 



o 



FPR = 0000000000000000 

-J FPR 2 = 83028201+OiiOOOIfAU 

FPR h = 20021FU800000000 

FPR 6 = 0000000000000000 



NJ 



027000 = 81818181 81818182 000167ttE F00273A0 00016i*DC 00000008 FFFD9002 06010002 

027020 = 20036758 10211021 10021UBC 00027000 00016390 00036C00 00036C10 A0016«iD8 

027040 = 00000000 00000000 0002818f| 0l»000'i98 00000000 00000000 00000000 00000000 

T, 027060 = FFOtiOOFE 70016766 00000000 00000000 00036D12 00036D10 0000116E 0000E672 

> • 027080 = 0000117II 00027000 0001A71A 00036C00 00036E18 'i001AB7A 00000002 0002816E 
z 0270A0 = 00028172 FFFFAOOl 21023625 00000008 00000002 05010002 20036758 10211021 

, 0270C0 = 100214BC 00027000 F003677C 00026300 070^*0088 00710100 00000061 060ti0090 

_ 0270E0 = 26040061 F00273A0 00013090 00000000 0650584D 5E565900 00000000 00000000 

g 027100 = 00000000 00000000 81870E81 870E8883 00CFE701 F161F1F5 00000100 OOOOOCOO 

027120 = OOOOFCOO 0000F800 0000F794 00001158 0000F7F8 00000010 00000001 07000000 

g 027140 = OOODOOOO 00780000 UD5856fiA 52578D4E 5B5B585B 9293888D 81870E81 870E8883 

2 027160 = 92935900 00000000 00020000 00000000 00000000 00000000 00000000 00000000 

- 027180 = 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
^ 0271A0 TO 027240 SUPPRESSED LINE(S) SAME AS ABOVE 

z 027240 = 00000000 00000000 80000001 84000000 00000000 00000000 00000000 00000000 

- 027260 = 00000000 60000005 00000000 00000000 00000000 00000000 00000000 00000000 

> 027280 = 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
0272A0 TO 0272C0 SUPPRESSED LINE(S) SAf4E AS ABOVE 

0272C0 = 00000000 07000000 00000000 00000000 00000000 00000000 00000000 00000000 

0272E0 = OBlOOBll 50030BOO F002017E 50000BOO F002017E 0005EA06 00000004 0A803502 

027300 = 000003FF FFFFF800 00000000 00000000 0001DF28 830192B4 F002017E FOOIABAC 

027320 = 0B020000 FOOIEDCE 4000046C 00000000 F00273A0 F002731C 0402626F F002780C 

T, 027340 = 8C023935 B7232340 00000008 10211021 07040088 F00230BC F0027430 F0027430 

^ 027360 = F00247CE F7022388 B7054461 DF020340 F001A4F6 70000B03 B7232340 F002736C 

fp 027380 = F0027348 700D0B00 00000000 00000000 00000C70 0000F460 3D8941BB 00000044 

^ 0273A0 = 00000002 00000002 00000000 00000000 00000000 00000000 00000000 00000000 

f 0273C0 = 2F04008D 2F000000 2F000001 2B0192D0 2B0192E4 2B0192F8 2B01930C 2B019320 

FIGURE 24.3.1: EXAMPLE WORKSPACE DUMP 



mm 



C3 

CD 



0273E0 = 2F000000 2B02801U 2B02802U 27000000 27000000 0FFE0070 0FFE0090 2F040088 
027400 = F00280BC 2B027F4C 2B027C08 2700005lf 2B03679if 3B02803I4 2B0367A8 27000054 
2?^^?2 " 27000042 2B036754 BB02809C 27000042 2F040061 9B0280E8 27000000 27000000 
;>^ 027440 = 27000000 27000000 27000000 27000000 27000000 27000000 27000000 27000000 

027460 TO 027800 SUPPRESSED LINE(S) SAME AS ABOVE 

027800 = 27000000 27000000 27000000 2F040063 2F04004A 2F04004F 2F04004B 2F040059 
027820 = 2F04005A 2F04005B 2F040050 2F040061 2F04005E 2B0280D8 99028158 040004A8 
027840 = 2B0281A0 0400049C 00000000 00000000 00000000 00000000 00000000 00000000 
027860 = 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 

^ 027880 TO 027C00 SUPPRESSED LINE(S) SAME AS ABOVE 

2 027C00 = 00000000 00000000 00000000 FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO 
^ 027C20 = FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO 
^ 027C40 TO 027F40 SUPPRESSED LiNE(S) SAME AS ABOVE ...,. 

, 027F40 = FFOOOOOO FFOOOOOO FFOOOOOO FFOOOOOO 0FFE0030 0FFE0002 2B0281F4 0F020080 

027F60 = 27000000 0F020090 27000042 OF020001 27000000 0FD1008C 0FD10074 0F000042 

2 ^rjJ^ " 60016001 2E010003 60016001 62016001 40054005 07010084 0FFE0040 0FFE0002 

027FA0 = 2B0281E0 0F020084 27000000 0FFE0080 2B028188 0F02007C 27000000 0F020078 

S 027FC0 = 27000000 0F020070 27000000 0F00005C 0F000094 0F000054 07010084 OF000028 

^ nllnl^r, ' 0P000002 27000018 OFOOOOOl 27000018 OFOOOOOl 27000018 OFOOOOOl 0F000498 

_ °28000 = 0F000018 07000000 08000002 00000005 OOOOOOOD 00500044 00000000 OOOOOOOD 

S 028020 = OOOOOOOD 00540048 00000000 OOOOOOOD 00000065 00540074 00030050 00000040 

2 028040 = 006C0070 0078007C 00800084 0002A001 007011D9 70010080 A0010078 10210070 

S Xo52^^ "^ 70010084 A0014005 60010106 00036001 04060061 00885005 00707001 006CA001 

^ 028080 = 0003A001 001A0024 0030004A 00000000 00000058 00000065 00000039 00540088 

0280A0 = 0001002A 00000030 008C0001 00900080 0002A001 01060002 10210090 7001008C 

028000= A0010003 A0010016 00240000 0000002C 00000039 OOOOOOOD 00540494 01505800 

0280E0 = OOOOOOOD 0000006D 00540094 0002005A 00000028 00010001 00010002 A0010106 

028100 = 00091109 7001007C 1101510A 00160000 00000003 00000003 00000002 70010084 

028120 = A0010106 00031109 10251591 11114001 01060003 11095001 00740084 A0010003 

^ S?^^'^^ " A0010014 00380054 00000000 00000060 0000006D 0000002D 00540498 OOOIOOIE 

^ 028160 = 00000028 00010001 00010002 A0010094 A0010003 A0010014 00180000 00000020 

n> 028180 = 0000002D 00000015 08D10C10 00000001 00000001 00000009 00000015 0000003D 

K, 2281AO = 007104A0 00000001 00000002 00000003 00000004 00000005 00000006 00000007 

f 028100 = 00000008 00000009 00000003 00000003 00000002 00000009 0000003D 00000011 

01 0281E0 = OIFIOCOO 007104A0 FFFF0070 00000011 00000011 01D10BB8 007104AO 0070FFFF 

FIGURE 24.3.2: EXAMPLE WORKSPACE DUMP 



So!o2S " 00000011 0000E5i*A 00000000 00000000 00000000 00000000 00000000 oooooonn 

s iiiiii ^or.vz\iiiTsii.rz\i] iiTTZT'" °°°°°°" °°"°°- »"°"" 

mill " "OOOOOOS 00000002 00000009 0000003D OOOOOOU 01F10070 llAlkM llllllll 
llllrl ' ^SSSSS" OO"'"""'' 0071007S 00000001 00000002 00000003 00000002 OOoSSm 
0367C0 = 00000006 00000005 00000006 00000009 00000003 00000003 Onnnnnn? nnnnnnno 

^ : sssss;^? sss§s:9'o° ziiiii zzi: zzz zzii zzz zz^ 

2 036C00 = 00000000 00000000 00000000 00000000 00016390 00036C0O OOO^finn AnniKhns 

036C20 = 000167t.E 00036C10 00036C20 6001G742 000167?E 0001672e F0027?JS nanifunr 

6CJ0 = 00000008 ^001A84A OOOOOOOO 00001158 5o5oE6AO OOO £3^9 SS OOgU OOo'oS'? 

s ^.^^roS ^ nS°^^"^^ 0003682C OOOOOOOO OOOOOOOO 00000000 0000FD13 00000001 OOOOOOOO 

036C80 = 00000001 OOOOOOOO OOOOOOOO OOOOOOOO 0001A71A 700199BC A002Q8GF nnnnPnin 

olfccn" nnnnnSSn 'nT'''' '''''''' '''''''' ''''''^' OO^OOOO 000 S 

036CC0 = OOOOOOOO OOOOOOOO OOOOOOOO 00000001 00001158 0000116E OOOOOOOO OOOOOOOO 

036CE0 = OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOnnnnn nnnnnnnn 

° 036D00 ^ 00001000 OOOOOOOO 00008D8D 8D8D8D8D 50589293 Je92935? 9293oS5A Sd5B9293 

- nllnln ^n'nTrT .?''''''' OOOOOOOO 00000000 00000000 0000 000 OOOOoS 2 SSoOOOOO 
_ 036040 TO 036E00 SUPPRESSED LINE(S) SAME AS ABOVE «^«^uuu uuuuuuuu 

^ n?rF?n ^ nnS?«??S ?nS?2??? OOOOOOOO OOOOOOOO OOOOOOOo' OOOOOOOO 0001A71A 5001B002 
nlllfn SoniJIJJ t^OOlDUeA 0001D79C 0000E5A0 0001E309 0000009^* OOOOOIOA OOOOOOOO 

^^ : ZZZ ZZ^l ZZll ZIZA ZZll ZZZ ZZll §S 



o 

o 
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FIGURE 2ii.3.3: EXAMPLE WORKSPACE DUMP 



25. FUNCTIONS IMPLEMENTED IN APL OR IBM/370 CODE 



Most of the APL operations are done by the microcode 
but some of them are done by APL functions or IBM/370 code. 
There^ are several reasons for using non-nicrocoded 
functions. There is only a small amount of control store 
and the amount of microcode has to be strictly limited. For 
some operations, the 370 code is almost as fast as a 
microcode implementation would be. Some operations are used 
relatively infrequently and they do not justify the use of 
microcode. Some operations, such as input/output, require 
extensive interaction v;ith the operating system; putting 
them in microcode would not improve performance and it would 
^ mal<e the emulator system dependent. Some operations, such 
^ as domino (matrix divide and least squares fit) are 
-^ obviously at a higher level than operations such as plus and 
minus; it is natural to put these operations in APL or 370 
code. 



25.1 The Calling Mechanism 

The non-microcode functions are used in several v/ays 
but they are all called in the same way. There is a control 
word named CALL370F which contains an address which we will 
denote by C, Beginning at Location C, there is a transfer 
vector with one entry per APL or 370 function. The transfer 
vector entries are shown in figure 25.1. Suppose the APL 
emulator is in control and it decides to call the dyadic 
Ibeam 370 function. The emulator puts the arguments of the 
Ibeam into the general purpose regl s ters ,us i ng the process 
specified in the section '370 REGISTERS AND 'GETV" It 
sets GPR4 equal to C. It sets the 370 instruction location 
counter equal to C + hexadecimal 8^4 (according to the table 
the dyadic Ibeam entry is 8k) and it exits to the 370 
emulator. Location C + 8A contains a branch to the 370 
function which does the dyadic Ibeam and it can use GPRij as 
a base register. The 370 function computes the result, if 
any, and uses an APLRTN instruction to return control to the 
APL emulator. The transfer vector, the 370 functions and 
the APL functions are resident in the APL system; the 
functions are re-entrant and may be used by any number of 
users. 
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IDO 



25.2 Scalar Functions 

Consider the execution of 'L d R' v/here L and R are 
variables and d is a scalar dyadic operator. The emulator 
does the steps described in the section on 'GETV then it 
does the follov/jng: 

check for character arguments 

if L and R are both scalar, then 
do operation 

check for 16 bit result, if so, put on stack 
else get space, store result and put descriptor 
^ and name on stack 

go to DONE 



if either L or R or both are non-scalar, then 

check that size of L conforms v/ith size of R 

get space for result 

go to EXIT if null result 

LOOP: do operation on first elements of L and R 
store result 

go to exit if all elements have been done 
get next tv;o elements and go to loop 

EXIT: put descriptor and name on stack 

DONE: free the space used by L and R if necessary 

Actually there is another step which is not described above; 
If the results of integer arithmetic overflow, then we 
convert all existing results to floating point and continue 
In floating point mode. If the operation is plus, minus, 
less than, etc., then the 'do operation' step is done 
completely in the APL emulator. In the following cases we 
go to a 370 function using the calling mechanism described 
in the previous paragraph: 

pov/er, log, real residue, binomial, circular 

We also call the '370 function' for real divide and some 
cases of real multiply but in these cases the transfer 
vector entries reduce to: 

DDR I*, 6 and MDR It, 6 
APLRTN APLRTN 
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D=3 



00 unused 
10 unused 
20 unused 
30 pov/er 
kd unused 
50 unused 
60 unused 
70 logarithm 
80 m I beam 
90 share-in 
AO take 
BO d iota 
CO unused 
DO execute 
EO inner prod 
FO m box 



Ok unused 
Ik floor 
-2k multiply 
5k deal 
kk unused 
5k unused 
6k residue 
7k unused 
8*^ d (beam 
9k share-out 
Ak drop 
Bk member 
Ck unused 
Bk unused 
Ek outer prod 
fk d box 



08 unused 
18 roll 
28 unused 
38 circle 
kB unused 
58 ! roll 
68 unused 
78 divide 
88 xten stack 
98 decode 
A8 grade up 
B8 unused 
C8 m dominoe 
D8 scan 
E8 m format 
F8 share-post 



OC unused 
IC factorial 
2C binomial 
3C unused 
^C unused 
5C unused 
6C unused 
7C unused 
8C xten name 
9C encode 
AC grade dovyn 
EC rotate 
CC d dominoe 
DC reduce 
EC d format 
FC unused 



FIGURE 25.1: 370 (OR APL) FUNCTIOM TRANSFER VECTOR 
(m=monadic, d=dyadic; 00 through 7C are 
scalar functions; 88, 8C and F8 are 
special functions which must return 
with APLSRTN) 
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In these tv^o cases the calling mechanism may seem somewhat 
elaborate but it ensures a clean interface between the APL 
and 370 emulators. In all of these dyadic scalar cases we 
are calling a 370 function with two 32 bit or 6U bit 
arguments and we expect a 32 bit or Bh bit result. The APL 
emulator does all the analysis of the arguments, fetch of 
the operands one at a time, conversion, if necessary, 
storing of result and counting the number of operations that 
must be done. As the 'DDR 4,6' implies, the left and right 
operands are real, they are in FPRif and FPRG, and the result 
goes In FPRt^. The 370 functions must save and restore any 
registers they use (other than FPR4, GPRk, GPRS and GPRA). 
If the 370 functions detect an error (for example, negative 
input to be logarithm routine) then they should go directly 
to the appropriate error exit in the APL system. The 370 
^ functions may look at the descriptor bits (see the section 
p on 'GETV') to determine the properties of the arguments. 

The reduction and inner and outer product routines go 
through a^ similar sequence and they call the same 370 
functions in the same way. The monadic operations, namely: 

floor, ceiling, factorial and roll 

use a similar process. There input is in FPR6 and, in the 
case of factorial and roll, the result should go in FPRij. 
The 'floor' routine Is required to do several things 
according to the following rules: 

Let X=GPR9 byte 1 bit 

Y=GPR9 byte 1 bit 1 

Z=GPRF byte 2 bit 

A=contents of FPR6 

if X=0 then set R equal to the ceiling of A, else set R 
equal to the floor of A 

If Y = l then put R into FPR/t 

if Y=0 and R can be expressed as a 32 bit integer, then put 
it in GPRS, else set 1=1 and put R in FPRU 

There is also a 370 function called 'I roll' which sets GPRS 
equal to a random choice from Iota N where N is the Integer 
in GPRG. 
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DO 



25.3 Complete 370 Functions 

In a case such as 'L d R' where d stands for dyadic 

Ibeam, then the emulator goes through 'GETV for L and R and 

then calls the 370 dyadic Ibeam function immediately. The 

emulator has checked that L and R have a value and If they 

were functions or shared variables then it will have got 

^u 'U)f^l"^^'. ^""^ '^ "^^^^ "° other checking. On entry to 
the 370 function the registers are as specified by 'GETV 
The 370 function should compute the result and put the stack 
entry for the result in GPR9. The result can be a stack 
entry for one of the following: 

null 

a stack Immediate 
^ a temporary or permanent variable 

an APL function 

All APL operations which can be used by the ordinary users 
must have a result. The null result can be used by system 
programmers but they must take care that it Is syntactically 
correct. In the first three cases, the APL emulator will 
free the space used by the arguments. If necessary, and 
return to the SCAN microcode. The fourth case is discussed 
below Monadic 370 functions are treated In the same way 
except that the 'left' argument will be missing and an 
immediate zero will have been substituted. 



25. I| APL Functions 

Any of the complete functions (but not the scalar 
functions of 25.2) may be written In either 370 code or In 
APL or in both; the emulator does not care which is used and 
the system programmer can make the choice. Suppose the 
system programmer decides to write dyadic domino in APL He 
writes the^ appropriate APL function, gets the internal 
representation of the APL function and produces a CSECT 
The easiest way of getting the CSECT Is to punch th4 
internal representation on cards In the form 

DC X'hexadecimal internal representation of APL function' 

and assemble It using the OS or DOS assembler. The CSECT is 
loaded as part of the APL system. When the APL emulator 
detects the dyadic domino operator, then it calls the 
appropriate 370 function. That 370 function should get a 
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fr^h^iH "^T'^tJ^^!!^ "^^ '^ '^'' '" th^ user's workspace. 
It should set the address table entry for 't' to: 

3F address of CSECT for APL domino function 
and should set GPR9 to 

3F uu internal name of t 

and do an APLRTN After the return the emulator will detect 

name''?s'^t'' K ?• '' .^.'''' f'^" '^^''^ ^^•- ^-notion whose 
name is t . Notice that only one copy of the domino 

function exists, but it can be used by any number of users- 
the arguments for the function, the local variables, and the 
status are stored in the user's workspace. When the 
emulator returns from a function which has the immediate bit 
on (see 'THE ADDRESS TABLE' for immediate bit) then if frees 
III . ^u""^: .'^'"? description should not be taken to imply 
A.oM 5*?^ domino in APLM is in APL code; one early version of 
37nln,t ''""?h-" ^PL d°"^'"°' but it may have been changed ?o 
emSla '''°'' "°^ require any change to the APL 



25.5 Microcode/370/APL Functions 

In the case of functions like domino or shared 
input/output, the emulator has no interest in what the 
functions do or how they do it. As long as they do not 
destroy the integrity of the workspace or the registers 
then any action or inaction is allowed. In the case of a 
of"^J'°AD encode, then the operation Is regarded as part 
of the APL processor and the microcode, 370, APL functions 
should complement each other. In these cases the 
microprogrammer will have specified what cases the microcode 
will do and what additional Information it will provide to 
the non-microcode functions. 



25.6 APLRTN 

Th. Am ^ APLRTN Instruction causes the following action. 
The APL emulator gets control, it checks the CUKWRD (see 

bv ' TTl^.W^'' f'^'^T^'^ INTERFACE'), and then It looks at 
byte 2 of GPRF, and it interprets that byte as follows: 
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uuuu uuOO return from scalar dyadic operation 

(see 25.2) 

uuuu uuOl return from scalar monadic operation 

(see 25.2) 

uuuu uulO return from complete function 

(see 25.3 and 25.1;) 

uuuu 0011 return from shared output or execute 

(see 25.7 and 25.8) 

uuuu 0111 return from shared input or execute 

(see 25.7 and 25.8) 

M In the cases which v/e have described so far then the 
^ emulator will have set GPRF byte 2 before it exits to be 370 
.g5 emulator so the 370 functions do not have to be av/are of 
this byte^ but some other cases v^i 1 1 change this byte. 



25.7 Shared Input and Output 

The emulator does not initiate any input or output, but 
It does call the system whenever I/O Is required. If the 
the end of an APL statement is reached, and the stack is not 
null, and the last operation was not an assii^n, then the 
emulator takes a ' pri nt/ trace' exit from APLSCAN. Another 
type of I/O is initiated when the emulator detects a shared 
variable or the quad symbol. Let S represent the quad or 
quad prime symbol or a shared variable. V.'hen the microcode 
SCAN routine reads the S then it calls the 370 'share-in' 
or 'share-out' function. At this stage the stack is: 



1) 


S <- 


2) 


S XX 


3) 


S< . . .> XX 


k) 


S<...> <- 



where xx is any symbol other than '<-'. S is in GPRl (see 
THE STACK'), and GETV has not been done. Case one causes a 
share-out' exit; the other three cases cause a 'share-in' 
exit. In cases three and four, the system will have to 
search down the stack until it finds the first closing 
bracket and then it can distinguish between the tv;o cases. 

In case one, the third item on the stack (which is in 
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GPR7) win be a variable. The system should check that the 
variable^ has a value and then transmit the appropriate 
information to the shared memory processor. The system 
should now move GPR7 into GPR9 and APLRTN. The contents of 

rPRF h^^ IVlll^'l be used. The emulator wi 1 1 have set 
GPRF byte 2 to 3 before exit. 

Now let us consider case two where S is not quad. The 
system should do the input and store the result in the 
workspace. The system should form either a stack immediate 
Cif the result is a scalar logical, character or short 
integer) or a stack entry for a temporary variable. In the 
latter case the system should have stored the result in the 

APLRTN should be given. The quad input case is similar to 
« the ordinary input case, except that the system should form 
^ a temporary function which contains the internal text of the 
■^ input. The system should put the stack entry for a niladic 

function in GPRl and then APLRTN. uiciuic 

A',.^'^^^^''u^^^J^^^^'^ ^^^ ^"'^"'^ ^^^ closing bracket and has 
distinguished between cases three and four then Mt should 
proceed as follows. For case three, simply proceed as in 
case tv;o. For case four, proceed as follows: The stack 
entry for the closing bracket was originally kO . . . It is 

^MAiVQ?;;; ^""f! ^u^'?C ^^ '" 'STATEMENT SCAN AND SYNTAX 
rPDi i li ^ should now be changed to kC. . . . Replace 
bPKl by the stack entry for a permanent variable which 
contains the latest value of S, then APLRTN. If there are 
no errors (possible errors are value, domain, index and 
workspace full), the emulator will do the subscripted assign 
f, ^P.nc ^^'!;,"11 the 'share-post' 370 routine. At this 
stage GPRF will contain the name of the subscripted 
variable, that is, the name which was formerly in GPRl The 
system should communicate whatever information is necessary 
to the shared memory processor, and then it should APLSRTN 



25.8 Execute 

Suppose the APL emulator encounters eX where e stands 
tor the execute operator. The emulator will do a 'g"eTV' and 
'^u^\^^^u ?^°. execute-operator function. That function 
should check that X is a legal character string, convert it 
to internal form, embed it in a temporary function 't' (see 
the section, on 'Temporary Functions' in 'FUNCTION' 
INVOCATION'), set GPR9 with the stack entry for 't' and 
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return. The emulator now follov^s the actions specified in 
section 25.it. 't' nay call other functions, including, of 
course, a recursive call to the function which called 't' 
The internal form of 't' should contain a trace bit at th4 
end of the statement one (there is only one statement) 
I'/hen the trace is reached, the emulator takes a normal trace 
exit. The system should save bit k of byte 2 of GPRii- let 
us denote this bit by 'a'. The stack contains the function 
call block for the call of 't' (see the 'Function Call" part 
of 'FUNCTION INVOCATION'). The system should remove the 
call block from the stack and then: 

If bit a=0 proceed as in shared input. Set GPRF byte 2 to 
7, GPRl equal to the result of the execute (if any) or null 
and GPR9,7... equal to the previous contents of the stack 

M Give an APLRTN. btacK. 

(ss) 

-§ If bit a=l then the execute ended with an assign and the 
emulator has to ensure that eX in the context ...+eX... does 
produce a result whereas eX in the context eX, . . . does not 
cause printing. In this case, proceed as in 'shared 
output', namely, set GPRF byte 2 to 3. GPRl and 7 are 
undefined. GPR9 is the result of the execute. GPRE, . . . has 
the previous contents of the stack. 

Obviously the procedure outlined in this section Is not 
simple but it requires very little extra 370 code or 
microcode and It gives a very powerful facility. 
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26. ERROR RECOVERY 



The use of the emulator may cause various errors to be 
detected. These errors can be divided into several types: 

1) Errors i n the user's program or data. 

2) System error' return from APLSCAN. 

3) Specification, data or addressing exceptions. 

k) Errors other than type 1 and 3 on return from APL 
macros other than APLSCAN. 

The first type of error will cause a 'syntax error', 'value 

error , etc. to be signalled on return from APLSCAN. This 

« type of error Is discussed below. The second and third type 

^ of error implies that the system or the emulator or the 

-fe^ hardware has a bug. I t wi 1 1 be necessary to dump the 

workspace and to trace the cause of the error- see 

DEBUGGING AIDS'. When this type of error is detected thin 

the workspace may contain unknown errors and execution on 

this workspace should not be continued. The fourth type of 

error is almost certainly due to a system program error and 

the cause should be easy to determine. 

^ Errors of type two, three and four should happen very 
infrequently. Errors of type one may happen quite 
frequently and they are a normal part of APL execution. 
When these errors occur the system should print out an 
appropriate message and then clean up the stack. To clean 
up the stack the system should delete all memory-stack 
entries back to the nearest STOP WORD, BEGIN STACK word or 
function CALL BLOCK. If a deleted item is the stack entry 
for a temporary variable then the name and the free space 
associated with the name (if any) should be freed; there is 
an APL macro for doing this. If the item which remains at 

J^H f ^?^P nnpr^^''T." ^ u^^'"'' ^^^^^^ ^^^" ^^^ ^^^tem should 
add a STOP WORD. The method of analysing the contents of 

the stack is given in the section on 'Status Indication' 

wnpn .'FUfTION INVOCATION'). The data needed for the S?Sp 

WORD IS found in the workspace in FUNCTION, NEXTINST and In 

the tail of the current function. Part of the stack 

information is held in the general purpose registers 

During the SCAN process, the registers will have the format 

described in 'THE STACK'; at other times the format of these 

registers will vary according to the operation being 

performed. ^ When an error occurs the format of these 

registers is unclear. It is possible that these registers 
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will contain the name of some temporary variables. The name 
and space of these variables must be released. These names 
cannot be determined from the registers, but they can be 
determined as follov/s: Search the address table for entries 
v/hlch belong to temporary variables. If such an entry is 
found then search all SCAM BLOCKS on the stack (see 'Status 
Indication' for a definition of SCAN BLOCK) for a use of the 
temporary variable. If no use is found then free the name 
and Its associated block in free space (if any). This 
search requires the system to look at every address table 
entry hov/ever the search is fast and it only occurs when APL 
execution has terminated due to a user error. 

There is another area which the error recovery 

procedure must check. The control word TMPNAMO usually has 

M the form 27...; after an error exit, if THPNAMO is 29... 

^ then It should be changed to 27... and the space whose 

^ address is in the low 2ii bits of TMPNAMO must be freed 

The same remarks apply to TMPNAfil. These control words are 

used to hold function arguements during the function call 

process. The arguements will have received permanent names 

by the time the function is entered and the control words 

will have been reset to 27... TMPNAMO may be used to hold 

the result of a function during the function return 

processing. 

if an error occurs in a locked function, a system 
runction, or a temporary function used for quad prime or 
execute, then the system will need to take special action. 
These actions are not defined by the emulator. 
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27. 370 EMULATOR/APL EMULATOR INTERFACE 



An earlier section described the APL macros which 
provide the interface between the APL system and the API 
emulator This section is concerned with the interface 
between the two emulators. i-cridut; 



27.1 APLEC Entry and Termination 

fh^ JpM °?^^ way for the APL emulator to gain control of 
the CPU^ IS for the 370 emulator to process the APLEC 
^ instruction. When the 370 emulator encounters an APLEC 

M \f^ll''''^l%? ^^^"^ ^^^ microcode does one of two things: (a) 

g If the APL emulator is not installed on this machine then 
give an operation exception. (b) If APL is Installed then 
activate it. When APL is activated it first checks the 
contents of CHKWRD; if it is incorrect then APL gives a 
specification exception, otherwise APL proceeds with 
emulation of the workspace. The test of CHKWRD safeguards 
against APL activation as a result of a wild branch in some 
370 program. If the emulator is working with a virtual 
memory then the test of CHKWRD accomplishes another vital 
function: It insures that the control words page of the 
workspace. IS in real memory. If the page is not in real 
memory when the APLEC instruction is encountered then a page 
fau t results and the 370 supervisor takes the normal page 
Imcr ^?^'°" of swapping the page into core and retrying the 
Setail below''"" ^''''^ ^^''^'' ^'^ disusssed in grfater 

^Tr'^!''!^u°". °^ ^^^ ^PLEC instruction is always 
accomplished by branching to APLM.XITNRM for a normal exit 
with condition code zero or by branching to APLM.XITERR for 
an error exit with condition code one. The APLM 
micro- routine then retrieves the address following the APLEC 
from SCANRTN or SERVRTN and sets it up as the 370 
instruction location. A return to l-cycles then Das<5P<? 
control back to the 370 emulator. passes 
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27.2 Page Faults 

_ The APL emulator must reference many memory locations 
during a single APLEC execution. It cannot anticipate 
possible page faults and force all pages to memory prior to 
real execution. Rather, page faults must merely cause 
execution to be suspended in a particular workspace until 
the required page Is available. Meanwhile execution may 
So? -T^.J" ^"°^''^'' ^^^r'^space. The following paragraphs 
detail this process using 'page fault' to mean a real 
translation exception; mere refreshing of the associative 
registers is handled by a microcode trap v/hich is 
transparent to the APL emulator. 

When the 370_ page fault routine is activated it tests 

M . ^Jr.^ emulation opcode and, if doing l^^Ol, It branches 

W ?.^ different set of instructions. This routine has been 

-^ altered to also test for an APLEC opcode and, if doing APL, 

It branches to the APL page fault routine. 

The APL page fault routine compares the faulting 
micro-address with that of the micro- I nstructlon in APLM 
which reads CHKWRD. If a match occurs it merely returns to 
the 370 page fault routine for normal 570 page fault 
processing. If there is a mismatch then the APL emulator 
was actively working in a workspace and must be 
checkpointed. Local storage and the faulting micro-address 
are^ saved In SAVELS and the 370 Instruction location 
register is set to point at the resume APLEC in I NTRTM The 
faulting memory address Is then loaded into an appropriate 
register and a branch made to the Instruction In APLM that 
reads CHKWRD. This causes a re-faulting that APL will allow 
^/O to process since It occurs on the 'read CHKWRD' 
mi cro- I nstructlon. 

When the paging software has the required page 
available and thinks It Is re-executIng the faulting 370 
instruction it will actually be executing the resume APLEC 
and the APL emulator will continue with the workspace 
execution. 
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27.3 Interrupts and Quantum Ends 

As well as making many memory references, execution of 
an APLEC nay require considerable time, at least in 
comparison to the execution times for most other 370 
instructions. Thus the APL emulator must be able to pause 
periodically. This is done in a manner similar to the above 
page fault processing. If the hardv/are requests a pause for 
an interrupt (II latch set) the APL emulator will checkpoint 
Itself in SAVELS exactly as above, set the 370 instruction 
location counter to point at I NTRTN and do a return to 
l-cycles from APLM. The workspace wi 1 1 be resumed later 
just as in the page fault case. 

Such an interrupt might be caused by a time-out 
^ initiated by the 370 APL system supervisor. If so It will 
set on the 'quantum end desired' switch and cause resumption 
of the v/orkspace by the APL emulator. As well as polling II 
the APL emulator polls the quantum end switch. If on, the 
emulator will checkpoint itself in SAVELS, set the 370 
instruction location register to the contents of QEND (i.e., 
it will point to the 370 APL system's quantum end routine) 
and do a return to i -cycles from APLM. As above, the 
workspace can be resumed later but to do so the 370 APL 
system must explicitly execute an APLRESM. 



27. If 370 Functions 

The APL emulator Is intended to co-reside with the 370 
emulator and must therefore limit the amount of control 
store it uses. To meet this end it has been necessary to 
put some of the slower and less frequently used opcodes, 
such as domino, and some of the cases where we wish to share 
the 370 emulator's microcode, such as floating divide, in 
external code (BAL or APL). Some of the less frequently 
used emulator features, such as extending the name table, 
have also been put in external code. The specific linkage 
conventions, etc., are discussed in 'FUNCTIOK'S IflPLEMENTED 
IN APL AMD IBfi 370 CODE'; here we merely complete our 
description of the Interface between the 370 and APL 
emulators. 

All breakouts to 370 functions are processed through 
the S370 microcode routine. There are no microcode linkages 
or V7orking storage to be saved. This routine merely sets 
the 370 Instruction location counter to point to the 
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appropriate entry in the 370 function transfer vector using 
CALL370F and branches to the conmon exit portion of APLM. 
When the 370 function is complete it will issue an APLRTN. 
The 370 emulator will decode the APLEC and branch to APLM; 
APLM win then recognize the 'return' APLEC code and branch 
to the S370 routine which will send control back to the 
appropriate place. 

Some of the emulator features which are coded as 370 
functions^ such as address table extension, require saving 
of microcode linkage and vjork registers. These checkpoint 
themselves in SAVELS as in the page fault case prior to 
going to S370. The corresponding 370 functions terminate 
with APLSRTN rather than APLRTN. This special return does 
not trickle back through S370; rather, the checkpointed 
information is recovered and control passed back to the 
invoking micro-routine via APLM and INTR. 



27.5 Summary Viewpoints 

There are tv/o major ways to look at the APLEC 
instruction. Each is given a paragraph description belov/. 
The first viewpoint is that seen from the 370 emulator. The 
second is that seen, or at least rationalized, by the APL 
system programmer. 

The APLEC instruction is a slow conditional branch as 
far as the 370 emulator is concerned. It sees tv/o cases: 
Sometimes APLEC is decoded into the APL emulator and after 
awhile a return to l-cycles is made with the 370 instruction 
location counter pointing at the point following the APLEC. 
At other times the return is accompanied by an instruction 
location counter pointing to some vastly different address 
(INTRTN, c(QEND), or some point in the 370 function transfer 
vector). in both cases the time spent in the APL emulator 
Is considerably longer than is spent executing a 370 'BC' 
instruction. The only way in which APLEC is different from 
other 370 instructions is that it may be decoded at location 
xyz, but cause a page fault as if it had decoded at location 
abc. 

V7hen the APL system programmer writes APLSCAN he uses 
it like a normal 370 instruction whose execution will always 
be followed by the execution of the next sequential 
instruction. He may know that the APL emulator can 
temporarily breakout at a different point such as the 370 
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wrUten"bv°''APriC?;i" '"' '"°=' °' "^^ "" functions were 
written by APL system programmers. But the 370 functions 

Shen ttl^'Ur^rlN™'' ''= "T" extensions of the JcrocoSe 
nex? instrSctfoT " '=°'"'"<'"' ^o"™' v" ' 1 return to the 
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28. DEBUGGING AIDS 



There are several debugging afds available. These are 
discussed below In 28.1 and 28.2. An example Is then 
discussed In 28.3. Figure 28.1 summarizes much of the 
debugging aids Information. These aids have been of great 
value during the early development stages but are of much 
less Importance now since bugs occur quite infrequently. 



28.1 DBUG Microcode Routine 

^ The DBUG microcode routine may be either active or 

^ Inactive. V^fhen active It monitors all entries to and exits 
-« ^''om the APL emulator (except the TIDY data exception: see 
28.2) and provides useful debugging Information. It 
represents considerable entry/exit overhead and should be 
Inactive, or not even assembled. In an Ideal situation. If 
the DBUG routine Is included in a microcode coreload, then 
after a normal IMPL DBUG is Inactive. Let XX denote 'the 
DBUG module' of the coreload (the value of XX may be found 
by consulting the DBUG routine listing for the coreload) 
To activate the DBUG routine the following control words 
must be patched in as part of the IMPL procedure (I.e. In 
the patch deck) or later (I.e. using the console 
alter/display facility): 

0000XX80 at APLM. CHECK. OX 
0000XX81 at APLM.SETNSI .00 
0100XX80 at PAGE.REFALT 

DBUG may be deactivated by patching these locations back to 
their assembled values. 

The DBUG routine uses a 'DBUG BOX' stored in the 
workspace. The DBUG box is at the location GPRB+(the 
contents of control store location XX08). The format of the 
DBUG box is given In figure 28.2. 

When DBUG Is active and any call Is made to the APL 
emulator, the DBUG box Is updated and the APLEC in byte 0-1 
of word of the DBUG box is executed. Similarly any exit 
from the APL emulator will be filtered through the APLEC in 
bytes 2-3 of this word. This provides two convenient 
address stop locations for emulator/system tracing. 
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DIALS •• XXlOwxyz (wxyz-mlcro address) 

2. When trap occurs press ALTER/DISPLAY, etc. 
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RATE to SINGLE CYCLE to check NREG. If It Is not XXIO 
you are temporar I 1 y In a 370 trap: set RATE to PROCESS 
and push START, say 'BOO' and repeat this Step. 
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In figure 28.2 ECNUM fs the current value of control 
store location XXOO, At IMPL this location Is set to zero 
and location XXOk is set to minus one. On each rla] 
emulator call (the pseudo calls out of the DBUG box are 
Ignored) XXOO is Incremented and XXOU Is decremented. The 
microcode Instruction DBUG. STOP. will be executed only when 
the countdown word reaches zero. This mechanism is for use 
with bugs that occur deeply Imbedded in an APL function 

hi^'L?"!^ °"^ ^''^"^r °" ^^^ ^y^t^"^ ^^^ count-up word can 
PrMMM^l^ ^?''° ^""^ the workspace run. When the bug occurs 
ECNUM determines a setting to key Into the count-down word. 
Using the microcode address stop switch It Is now possible 
to rerun the workspace and stop on the entry during which 
the problem will show up. Then one can micro-step, etc. 

^ ^ »wl«® ^^^^ package also contains a 'return to I-cvc1p<5« 
^ at XXOC and a 'stop and branch to XXIO' at XXIO The firit 

"^ SIc = *^^^^r '\"^^^"' !" recovering from an APL emulator 
disaster (such as a micro-loop). The second Is useful in 
conjunction with alter/display and the microcode address 
trap console feature. 

28.2 Other Aids 

4.t, Jn? ^^^f sections of this document we have described 
the APL emulator and the emulator/system Interface. We have 
deliberately avoided any specification of the system. This 
gives the system programmer greater flexibility In designing 
the system and_ allows him to change the system without 
Thf'nm,r\ ni.crocode. In this section we have described 
the DBUG box which is in the system's part of the workspace 
We further note that the system usually precedes each APL 
macro wi th 

LM 't,3,X'A8«{ll) 

and follows the macro with a corresponding STM. These 
things are true for the present system but they are not part 
of the emulator or system specifications. 

During garbage col lect Ion the TIDY microcode routine 
checks each active block In free space for a correct back 
pointer (address table or stack entry). On errors it gives 
a data exception with the PSW pointing at the word after the 
DN word. On these dumps the collection will be partly done; 
It will have . proceded to the error block so the free space 
format may look strange. This code could be removed If the 
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emulator and system could be judged perfect, but It costs 
relatively little In terms of overhead. 

On exits for page faults, to take interrupts, or any 
other exit that passes through the INTR microcode routine, 
local storage will be saved in SAVELS. The format is: LS1£*, 
LS15, LS16, LS.17, W, V, I, LS13 (the linl<age register), SUTL 
where SUTL Is SPTL with U(3) replacing P. This Is a 
permanent emulator feature. 

On APL error exits, i.e., exits which pass through the 
ABEN microcode, local storage Is saved In SAVELSB In the 
same format as above; however, the ABEN routine will have 
altered a^ few of the registers (see the microcode listing 
for details). This is temporary code which should be 
^ removed eventually. 



IS2) 



In addition to the above aids there are the obvious 
things to look for In workspace dumps: what Is NEXTINST? 
the current APL opcode (GPR9)? the common linkage registers 
(GPRA, FPRtt, GPRD)? the error linkage register (GPRti)? 

Finally there Is the APLDIAG Instruction. This Is used 
mainly in testing areas where there may be a machine 
malfunction or a misunderstanding of the microcode 
Instruction specifications. Consult the source listings for 
comments at the APLDIAG decode point In the SERV routine. 



28.3 An Example 

Figure 28.3 lists debugging Information found in a 
workspace dump. V^e will begin to examine the dump as an 
Illustration of debugging techniques. The actual control 
store addresses and microinstruction sequence numbers are 
obviously valid only for the APL emulator as assembled on 
the date of the dump. 

We first note that the emulator last exited for a page 
fault (DBUG BOX: THIS EXIT). The faulting address was 
SitOOXX (DBUG BOX: PFADR). This is outside the address space 
of the particular machine which was running (DUMP PSW 
confirms an addressing exception) so the emulator must have 
develo'ped a bad address. 

The microinstruction causing the page fault was at 
control store location 5BE8 (SAVELS: LINK) which Is 
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FIGURE 28.3: EXAMPLE DUMP INFORMATION 
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FUNN.131. That instruction is 'RDH LS17 ADJ,W+2' and we can 
see that W was indeed 005U006C (SAVELS: W). 

The bad contents of V/ look suspiciously like the DN 
word for a character vector (D = 005't). This can be quickly 
supported; GPRS is added to 005C to find the address table 
entry for the variable with Internal name 006C. This entry 
is gBOZSOSi*. Syntax code 9 is a niladic function and the 
internal form of all functions is 'character vector'. 
Indeed/ when we look at location 028031; we find the 005U006C 
DN word. We now have a good handle on the bug which we 
suspect to be In the function call mechanism. 

Some of the other debugging information which might 
have proved useful includes: The emulator was last entered 
^ by a return from the 370 function (DBUG BOX: LAST ENTRY) 
having an APLRTN at address 0163'+0-2 (DBUG BOX: LAST LOO. 
There Is a history of ASGN calling GETV (LINKAGE REGISTERS: 
GPRA) and of SERV calling FREE (LINKAGE REGISTERS: GPRD). 



DO 
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29. CONCLUSIONS 



The architecture of the APL processor and the design of 
the 370 emulator/APL emulator interface was completed in 
October 1970. The implementation of both microcode and 
softv/are was begun soon afterwards. Some design changes 
v/ere made as the implementation progressed^ but on the whole 
fev/ changes were necessary. Shared variables were added at 
a later stage, but since the bulk of the shared variable 
processing is done by the software, few changes were 
required in the emulator. Almost all of the microcode 
debugging was done using simulation. An initial and partial 
version of the emulator and the APLM system was operational 
c=g in November 1971. A complete emulator and APLM system was 
(ss) running successfully and reliably in April 1972. It is 
g reasonable to expect that any system will contain some 
errors; one of the problems with errors in microcode is that 
they may be confused with hardware errors and they may cause 
the operating system to fail d isas terously. The APL 
emulator has been used for several months on a model 1U5 
which supports general scientific computing and systems 
programming under a CP operating system (the system is 
similar to CP/67 but operates on a model IfiS). During this 
time the emulator has never caused the system to fail and 
has never caused an error which looked like a hardware 
problem. 

The execution of APL programs is done partly by the 
microcode and partly by the software. At the current time 
the status is as follows ... 

(a) Completely in microcode: 

statement scan and syntax analysis 

management of free space and garbage collection 

function call and return 

plus, minus, negative, signun 

magnitude, maximum, minimum 

all logical operations 

al 1 compar i sons 

size, reshape, catenate, laminate, ravel 

index generator, compress, expand 

reverse, transpose 

goto, assignment, subscripting 

integer cases of times, residue, floor, ceiling 



06/20/72 LPASM - ! BM CONFIDENTIAL Page 29.1 



(b) Analysis and operand fetch/store 

operation on one element or one pair 
done in IBM 370 code: 



in microcode; 
of elements is 



C=3 

E3 



power/ exponential, logarithm, binomial 
circular, real residue, factorial 
real, multiply, pi, divide, reciprocal 
real floor, real ceiling 

(c) Done by the APLM system; may be in APL or IBM 370 code: 

grade up, grade down, roll, deal, domino 

scan, format, translation part of execute, Ibeam 

input/output 



(d) The remaining I terns are: 
Index of 



I n 



APL; will be 



membershi p 
encode, decode 

take, drop 



rotate 



inner product 



outer product 
reduct Ion 



wi 1 1 
the 



be 



currently 

microcoded 

same 

currently in APL; 

partially microcoded 

in microcode if the left 

argument has one element; 

otherwise in APL but will be 

in IBM 370 code 

in APL if the right argument 

Is an array; otherwise in 

mi crocode 

In APL if either argument 

an array; otherwise 

ml crocode 

same 

scalar and non-AP vector 

microcode; rest in APL 



I s 
i n 



I n 



The microcode for the APL emulator occupies 
control memory and can co-reside v;i th an IBM 
which will fit In the remaining khK byte 
conveniently have put the items in class (d) 
In rows three and four of class (b) In micro 
not do so because of a lack of space. The u 
code for Items in rows one and two of class 
satisfactory and we can see no reason for mic 
Likewise, there is no reason to alter class 
operation might seem like a good candidate for 
a superficial examination indicates that on 
the microcode would not be appreciably faster. 



20K bytes of 

370 emulator 

s. \le could 

and the I terns 
code but wi 1 1 
se of IBM 37 

(b) is qui te 
rocoding them. 
(c); the grade 

microcode but 
the model ItiS 
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It Is obvious that a project of this size and 
complexity will utilize the programs, techniques and 
co-operation of a number of people. The emulator was 
written in a microprogramming language designed by D. L. 
McNabb and J. R. Walters ('MPL/lii5 A Language and Compiler 
for System/370 Model Ikb Microprogramming', Palo Alto 
Scientific Center report number ZZ20-61j10). The use of this 
language played a major part in helping us to write and 
debug the APL emulator and we believe that it provides 
excellent documentation for the finished product. The 
debugging of the emulator was greatly simplified by an 
excellent and reliable assembler and simulator provided by 
the model 145 group in SDD, Endicott; we are also Indebted 
to V^. Decker, R. Dunbar, G. KInsella and E. Wassel of that 
« group for answering many questions about the v/orklngs of the 
^ hardware and the assembler and simulator. The authors of 
-^ this report were responsible for the design of the 
architecture as well as the writing and debugging of the 
microcode. M. J. Beniston was responsible for the design 
and Impl imentation of all the APLM software for use under 
CMS; this v;ork, to be reported elsewhere, includes the 
softv/are for the translator, the editor, shared variables, 
error recovery, format, the 370 functions, etc. J. W. 
Lageschulte used the APL/360 and CMS/APLM systems to develop 
the stand alone and OS versions of APLM. H. R. Penafiel 
wrote an early version of the translator and part of an 
Interpreter In IBM 370 code which was used In checking out 
the softv/are. R. J. Creasy provided advice and 
encouragement throughout the project, wrote a number of the 
APL system functions and solved one of our major problems by 
pointing out that the problem could not occur. 
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report number ZZ20-6402) 

This describes an earlier and different microcoded 
version of APL on the model 25. It shares many of 
the concepts and is somewhat more narative. 



A. Hassitt 
■ay Subs( 
and Development ^ IC No. 



and L. E. Lyon, "Efficient Evaluation of 
Array Subscripts of Arrays", IBM Journal of Research 

1/ ifS-B? (1972) 



This provides an APL description of the methods 
used by the microcode subscripting routines. 
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31. MICRO-ROUTINE NAMES 



Other portions of this document refer to specific 
microcode routines by name (i.e. SCAN or GETV). These are 
the names used for the routines during most of the 
development stages. When the routines were actually merged 
with the 370 routines it became necessary to rename the 
routines. The corespondence follows: 



DEVELOPMENT NAME 



FINAL NAME 



3: 



ABEN 

APLM 

APVX 

ASGN 

BASE 

CHIX 

CMEX 

COMA 

COPY 

OBUG 

DIVI 

DM IX 

DYAD 

DYOP 

DYOV 

DYSC 

DYVC 

EPS I 

FINS 

FRNS 

FUNN 

GETN 

GETV 

GOGO 

INDA 

INDB 

INDC 

INDD 

INDE 

INTR 

MM IX 

MNAD 

MULT 

PAGE 



PLAA 

PLAB 

PLAC 

PLAD 

PLBW 

PLAE 

PLAF 

PLAG 

PLAN 

PLDB 

PLBX 

PLAI 

PLAJ 

PLAK 

PLAL 

PLAM 

PLAN 

PLBY 

PLAO 

PLAP 

PLAQ 

PLAR 

PLAS 

PLAT 

PLAU 

PLAV 

PLAW 

PLAX 

PLAY 

PLAZ 

PLEA 

PLBB 

PLBC 

PLBD 
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PROD PLBE 

REAL PLBF 

REDU PLBG 

ROTA PLBH 

RSHP PLBI 

SCAN PLBJ 

SCN2 PLBK 

SERV, PLBL 

SKIP PLBM 

STOR PLBN 

SYNN PLBO 

S370 PLBP 

TIDY PLBQ 

TKDP PLBR 

TRAN PLBS 

TRED PLBT 

UNFN PLBU 

XTEN PLBV 
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